{"openapi":"3.1.0","info":{"title":"AutoClips API","version":"1.0.0","description":"Create, edit and check Character Explainer, 3D Animated Studio 2.0, AutoClips V3, Stickman, Fruit AI Stories and Animal Stories videos — everything the app can do.\n\nAuthenticate with `Authorization: Bearer <API key>` (Settings → API in the app).\nMoney is always explicit: paid calls need `max_credits` or a `quote_token`. Paid calls, and the free calls whose `Idempotency-Key` parameter is marked required (such as making a new project), need that header: a fresh UUID per new request, so a retry never runs or charges twice.\nEvery signed-in answer carries `RateLimit-Policy` and `RateLimit` (IETF draft) for the per-account minute limit and any daily limit the request counted against, plus `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (seconds) for the minute limit. Every 429 carries `Retry-After` in seconds.\nThis document describes every operation. A smaller one: `https://app.autoclips.app/api/v1/openapi.json?product=v3` (one product, plus the shared calls every video needs: who the key is, options, quotes and jobs, and the shared calls that take that product, for V3 `shared.timeline.*`, `shared.videos.*` and `shared.covers.*`), or `https://app.autoclips.app/api/v1/openapi.json?operation=v3.projects.quick_create` (just the operations named; several separated by commas). Each operation has a working example of its request.\nFull guide with every option and example: https://app.autoclips.app/developers"},"servers":[{"url":"https://app.autoclips.app/api/v1"}],"tags":[{"name":"Account, media and publishing"},{"name":"AutoClips V3 (cinematic stories)"},{"name":"Character Explainer"},{"name":"3D Animated Studio 2.0"},{"name":"Stickman videos (Explainer, Skit, Story)"},{"name":"Fruit AI Stories and Animal Stories"}],"paths":{"/automations":{"get":{"operationId":"shared_automations_list","summary":"List your Talking Objects, Miniature, Text Story and Quiz automations with their settings, schedule and daily limit.","description":"List your Talking Objects, Miniature, Text Story and Quiz automations with their settings, schedule and daily limit.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.automations.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_automations action=list","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automations":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: talkingObjects, miniature, textStory, quiz.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false}}},"required":["automations"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"automations":[{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Daily Quiz","format":"quiz","status":"active","pauseReason":null,"schedule":{"timezone":"America/Chicago","times":["12:00"],"videosPerDay":1},"settings":{"niche":"surprise","nicheRotation":[],"mode":"standard","questionCount":10,"timerSeconds":4,"theme":"surprise","language":"en","narration":true,"gameplay":"random","musicVolumeDb":-14,"voice":null,"music":{"mode":"library","category":"upbeat"}},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":100,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":100,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"shared_automations_create","summary":"Set up a Talking Objects, Miniature, Text Story and Quiz automation that makes and posts videos on a schedule, within a daily limit.","description":"Makes an automation of one of these formats with every option of its wizard: send exactly one of talkingObjects, miniature, textStory or quiz. At each posting time it makes a new video, and posts it. What you approve is its daily spending limit (spendLimitPerDay; left out, one day of runs at their most): a run that would pass it is skipped until the next day, and a run is settled after it is made, so one step's final cost can run a little over. A value the app would not keep for these settings is refused (400 setting_not_allowed). With publishing, every video is posted automatically: that needs the publish permission, accounts must be yours and platforms on your plan, and the approval names them. The same request again with the same Idempotency-Key hands back the same automation.\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. Short format automation day stops before a step that would go past the limit, but one step's final cost can run a little over, so the limit is not the most it can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"shared.automations.create","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"autoclips_automations action=create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The automation's name: unique on your account, at most 100 characters.","type":"string","minLength":1,"maxLength":100},"schedule":{"description":"When it runs. A new automation needs all three; an update changes only what you send.","type":"object","properties":{"timezone":{"description":"The time zone of the posting times (IANA, for example \"America/New_York\").","type":"string","minLength":1,"maxLength":64},"videosPerDay":{"description":"Videos a day, 1 to 3: one per posting time.","type":"integer","minimum":1,"maximum":3},"times":{"description":"The posting times, one per video a day (\"09:00\", 24-hour).","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}}},"additionalProperties":false},"talkingObjects":{"description":"A Talking Objects automation: everyday objects explain themselves.","type":"object","properties":{"objectCategories":{"description":"Which objects talk: fruits, vegetables, proteins, spices, grains, supplements, superfoods, nuts. At least one, or customCategory.","maxItems":8,"type":"array","items":{"type":"string","enum":["fruits","vegetables","proteins","spices","grains","supplements","superfoods","nuts"]}},"customCategory":{"description":"Your own objects, comma separated (\"Honey, Olive Oil\").","type":"string","minLength":1,"maxLength":500},"environment":{"description":"Where they talk: body, kitchen, garden, plate.","type":"string","enum":["body","kitchen","garden","plate"]},"model":{"description":"omniMax (Pro Max), veo31fast (Pro) or budget (Lite: a picture, a voice and animation). Priced per clip.","type":"string","enum":["omniMax","veo31fast","budget"]},"clipCount":{"description":"Clips in a video, 1 to 9. Priced per clip.","type":"integer","minimum":1,"maximum":9},"aspectRatio":{"type":"string","enum":["9:16","16:9","1:1"]},"language":{"description":"The spoken language. One the format cannot speak is refused (setting_not_allowed).","type":"string","minLength":2,"maxLength":12},"voice":{"description":"The voice, only with model budget: a voice id or name from autoclips_voices.","type":"string","minLength":1,"maxLength":120},"music":{"description":"The background music.","type":"object","properties":{"mode":{"description":"none, or library: a random track of a mood.","type":"string","enum":["none","library"]},"category":{"description":"A mood of the music library (a random track of it per video): popular, playful, sneaky, mysterious, epic, chill, upbeat, whimsical, v3-animals, v3-crime, v3-general, v3-history, v3-horror, v3-science, v3-space.","type":"string","enum":["popular","playful","sneaky","mysterious","epic","chill","upbeat","whimsical","v3-animals","v3-crime","v3-general","v3-history","v3-horror","v3-science","v3-space"]}},"required":["mode"],"additionalProperties":false},"musicVolumeDb":{"description":"The music under the video, -40 to 0 dB.","type":"number","minimum":-40,"maximum":0}},"additionalProperties":false},"miniature":{"description":"A Miniature World automation: a tilt-shift tiny world with an ambient soundscape.","type":"object","properties":{"angle":{"description":"The tiny world: rescue, farming, cooking, construction, city, custom.","type":"string","enum":["rescue","farming","cooking","construction","city","custom"]},"angleRotation":{"description":"fixed keeps the angle; rotate picks a new one each run.","type":"string","enum":["fixed","rotate"]},"storyMode":{"description":"anthology: a new tiny story every video; continuous: one world going on.","type":"string","enum":["anthology","continuous"]},"videoModel":{"description":"omniMax (Pro Max), kling3 (Pro) or veo31lite (Lite). Priced per clip.","type":"string","enum":["omniMax","kling3","veo31lite"]},"sceneCount":{"description":"Clips in a video, 4 to 8. Priced per clip.","type":"integer","minimum":4,"maximum":8},"music":{"description":"The background music.","type":"object","properties":{"mode":{"description":"none, or library: a random track of a mood.","type":"string","enum":["none","library"]},"category":{"description":"A mood of the music library (a random track of it per video): popular, playful, sneaky, mysterious, epic, chill, upbeat, whimsical, v3-animals, v3-crime, v3-general, v3-history, v3-horror, v3-science, v3-space.","type":"string","enum":["popular","playful","sneaky","mysterious","epic","chill","upbeat","whimsical","v3-animals","v3-crime","v3-general","v3-history","v3-horror","v3-science","v3-space"]}},"required":["mode"],"additionalProperties":false},"musicVolumeDb":{"description":"The music under the video, -40 to 0 dB.","type":"number","minimum":-40,"maximum":0}},"additionalProperties":false},"textStory":{"description":"A Text Story automation: a chat conversation told over gameplay.","type":"object","properties":{"category":{"description":"The kind of story: horror, revenge, drama, workplace, paranormal.","type":"string","enum":["horror","revenge","drama","workplace","paranormal"]},"categoryRotation":{"description":"fixed keeps the category; rotate goes through them.","type":"string","enum":["fixed","rotate"]},"premiseMode":{"description":"auto: a fresh premise each run; custom: premiseText.","type":"string","enum":["auto","custom"]},"premiseText":{"type":"string","minLength":1,"maxLength":1000},"language":{"description":"The spoken language. One the format cannot speak is refused (setting_not_allowed).","type":"string","minLength":2,"maxLength":12},"theme":{"description":"The chat's look: dark_blue, light_classic, amoled_green, midnight_purple, imessage_light, imessage_dark, or null for a fresh one each run.","anyOf":[{"type":"string","enum":["dark_blue","light_classic","amoled_green","midnight_purple","imessage_light","imessage_dark"]},{"type":"null"}]},"layoutMode":{"type":"string","enum":["chat_over_gameplay","full_chat"]},"gameplayCategory":{"description":"The gameplay behind the chat: minecraft, roblox, gta, subway, asmr.","type":"string","enum":["minecraft","roblox","gta","subway","asmr"]},"gameplayId":{"description":"One clip of the gameplay library, or null for a surprise.","anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"audioMode":{"description":"dual_voice, narrator or music_only. It sets the price.","type":"string","enum":["dual_voice","narrator","music_only"]},"voiceA":{"description":"The first voice: a voice id or name from autoclips_voices.","type":"string","minLength":1,"maxLength":120},"voiceB":{"description":"The second voice.","type":"string","minLength":1,"maxLength":120},"ttsModel":{"description":"null: Expressive (default); eleven_multilingual_v2: the older model.","anyOf":[{"type":"string","enum":["eleven_multilingual_v2"]},{"type":"null"}]},"lengthSeconds":{"anyOf":[{"type":"number","const":60},{"type":"number","const":75},{"type":"number","const":90},{"type":"number","const":105},{"type":"number","const":120}]},"paceSpeed":{"description":"How fast the messages come, 1 to 4.","type":"number","minimum":1,"maximum":4},"scriptMode":{"description":"The writer: normal or max. It sets the price.","type":"string","enum":["normal","max"]},"chatSounds":{"type":"boolean"},"cliffhanger":{"type":"boolean"},"music":{"description":"The background music.","type":"object","properties":{"mode":{"description":"none, or library: a random track of a mood.","type":"string","enum":["none","library"]},"category":{"description":"A mood of the music library (a random track of it per video): popular, playful, sneaky, mysterious, epic, chill, upbeat, whimsical, v3-animals, v3-crime, v3-general, v3-history, v3-horror, v3-science, v3-space.","type":"string","enum":["popular","playful","sneaky","mysterious","epic","chill","upbeat","whimsical","v3-animals","v3-crime","v3-general","v3-history","v3-horror","v3-science","v3-space"]}},"required":["mode"],"additionalProperties":false},"musicVolumeDb":{"description":"The music under the video, -40 to 0 dB.","type":"number","minimum":-40,"maximum":0}},"additionalProperties":false},"quiz":{"description":"A Quiz automation.","type":"object","properties":{"niche":{"description":"surprise rotates the packs (best: a pinned pack runs out of new questions), or one pack id.","type":"string","enum":["surprise","flags","capitals","geography-mix","countries-by-emoji","animals","animal-babies","ocean-life","dinosaurs","food","fruits-vegetables","movies-by-emoji","songs-by-emoji","history","guess-the-year","science","space","human-body","world-records","country-superlatives","inventions","mythology","sports-rules","brainrot-slang","english-vocab","phrases-by-emoji","professions-by-emoji","landmarks","everyday-objects","musical-instruments","math-teasers","odd-one-out","true-or-false-myths","would-you-rather","general-knowledge"]},"nicheRotation":{"description":"Your own list of packs to go through.","maxItems":34,"type":"array","items":{"type":"string","enum":["flags","capitals","geography-mix","countries-by-emoji","animals","animal-babies","ocean-life","dinosaurs","food","fruits-vegetables","movies-by-emoji","songs-by-emoji","history","guess-the-year","science","space","human-body","world-records","country-superlatives","inventions","mythology","sports-rules","brainrot-slang","english-vocab","phrases-by-emoji","professions-by-emoji","landmarks","everyday-objects","musical-instruments","math-teasers","odd-one-out","true-or-false-myths","would-you-rather","general-knowledge"]}},"mode":{"description":"standard, or blitz (a short under 61 seconds).","type":"string","enum":["standard","blitz"]},"questionCount":{"description":"Questions: 8 to 15 in standard, 3 to 6 in blitz.","type":"integer","minimum":3,"maximum":15},"timerSeconds":{"anyOf":[{"type":"number","const":3},{"type":"number","const":4},{"type":"number","const":5}]},"theme":{"type":"string","enum":["surprise","neon_dark","clean_light","retro_arcade","gradient_pop"]},"language":{"description":"The spoken language. One the format cannot speak is refused (setting_not_allowed).","type":"string","minLength":2,"maxLength":12},"narration":{"description":"A voice reads the questions.","type":"boolean"},"voice":{"description":"The voice: a voice id or name from autoclips_voices, or null for the language's default.","anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"gameplay":{"description":"none, random or one clip of the gameplay library.","type":"string","minLength":1,"maxLength":120},"music":{"description":"The background music.","type":"object","properties":{"mode":{"description":"none, or library: a random track of a mood.","type":"string","enum":["none","library"]},"category":{"description":"A mood of the music library (a random track of it per video): popular, playful, sneaky, mysterious, epic, chill, upbeat, whimsical, v3-animals, v3-crime, v3-general, v3-history, v3-horror, v3-science, v3-space.","type":"string","enum":["popular","playful","sneaky","mysterious","epic","chill","upbeat","whimsical","v3-animals","v3-crime","v3-general","v3-history","v3-horror","v3-science","v3-space"]}},"required":["mode"],"additionalProperties":false},"musicVolumeDb":{"description":"The music under the video, -40 to 0 dB.","type":"number","minimum":-40,"maximum":0}},"additionalProperties":false},"topics":{"description":"Where the ideas come from, and how each video ends.","type":"object","properties":{"mode":{"description":"category: ideas on a topic category; custom: ideas on your own theme.","type":"string","enum":["category","custom"]},"category":{"description":"The topic category: history, science, horror, psychology, tech, nature, money, health, weird, crime, space, food.","type":"string","enum":["history","science","horror","psychology","tech","nature","money","health","weird","crime","space","food"]},"customTopic":{"description":"Your own theme for new ideas.","type":"string","minLength":1,"maxLength":2000},"style":{"description":"The video style: engaging, educational, comedy, story, brainrot.","type":"string","enum":["engaging","educational","comedy","story","brainrot"]},"goal":{"description":"What the videos are for: views, followers, sales, awareness, custom.","type":"string","enum":["views","followers","sales","awareness","custom"]},"goalText":{"description":"Your own goal in words, with goal custom.","type":"string","minLength":1,"maxLength":500},"cta":{"description":"The call to action at the end: none, follow, subscribe, share, custom.","type":"string","enum":["none","follow","subscribe","share","custom"]},"ctaText":{"description":"Your own call to action, with cta custom.","type":"string","minLength":1,"maxLength":200},"commentWord":{"description":"The word viewers comment, with cta comment.","type":"string","minLength":1,"maxLength":40},"commentReward":{"description":"What they get for it, with cta comment.","type":"string","minLength":1,"maxLength":120},"visitUrl":{"description":"Where to send viewers, with cta visit: said in the video, never fetched.","type":"string","minLength":1,"maxLength":200}},"additionalProperties":false},"publishing":{"description":"Where each video goes. Switching posting on, changing the posting account or making YouTube videos more public needs the publish permission; only the platforms you send change.","type":"object","properties":{"email":{"description":"Email you when each video is ready.","type":"boolean"},"library":{"description":"Keep each video in My Videos.","type":"boolean"},"tiktok":{"description":"Posting to TikTok.","type":"object","properties":{"enabled":{"description":"Post every video to TikTok.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"youtube":{"description":"Posting to YouTube.","type":"object","properties":{"enabled":{"description":"Post every video to YouTube.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"},"privacy":{"description":"public, unlisted or private (default private; private videos get no comments, so no votes).","type":"string","enum":["public","unlisted","private"]},"categoryId":{"description":"The YouTube category id (2 Autos & Vehicles, 23 Comedy, 27 Education, 24 Entertainment, 1 Film & Animation, 20 Gaming, 26 Howto & Style, 10 Music, 25 News & Politics, 29 Nonprofits & Activism, 22 People & Blogs, 15 Pets & Animals, 28 Science & Technology, 17 Sports, 19 Travel & Events).","type":"string","enum":["1","2","10","15","17","19","20","22","23","24","25","26","27","28","29"]},"useAIMetadata":{"description":"Write the title and description from the video (default true).","type":"boolean"}},"required":["enabled"],"additionalProperties":false},"instagram":{"description":"Posting to Instagram.","type":"object","properties":{"enabled":{"description":"Post every video to Instagram.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"facebook":{"description":"Posting to Facebook.","type":"object","properties":{"enabled":{"description":"Post every video to Facebook.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"twitter":{"description":"Posting to X.","type":"object","properties":{"enabled":{"description":"Post every video to X.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"snapchat":{"description":"Posting to Snapchat.","type":"object","properties":{"enabled":{"description":"Post every video to Snapchat.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false}},"additionalProperties":false},"spendLimitPerDay":{"description":"The most it may spend a day, in credits (1 to 100,000). Left out: one day of runs at their most.","type":"integer","minimum":1,"maximum":100000},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["name","schedule"],"additionalProperties":false},"example":{"name":"Daily Quiz","schedule":{"timezone":"America/Chicago","videosPerDay":1,"times":["12:00"]},"quiz":{"niche":"surprise","mode":"standard","questionCount":10,"music":{"mode":"library","category":"upbeat"}}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: talkingObjects, miniature, textStory, quiz.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"approvedCreditsPerDay":{"description":"The daily spending limit you approved.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["automation","approvedCreditsPerDay"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Daily Quiz","format":"quiz","status":"active","pauseReason":null,"schedule":{"timezone":"America/Chicago","times":["12:00"],"videosPerDay":1},"settings":{"niche":"surprise","nicheRotation":[],"mode":"standard","questionCount":10,"timerSeconds":4,"theme":"surprise","language":"en","narration":true,"gameplay":"random","musicVolumeDb":-14,"voice":null,"music":{"mode":"library","category":"upbeat"}},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":100,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":100,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},"approvedCreditsPerDay":100}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/automations/brands":{"get":{"operationId":"shared_automations_brands","summary":"List your brands, for a Character Explainer or V3 automation's brand choice.","description":"List your brands, for a Character Explainer or V3 automation's brand choice.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.automations.brands","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_automations action=brands","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"brands":{"type":"array","items":{"type":"object","properties":{"brandId":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["brandId","name"],"additionalProperties":false}}},"required":["brands"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"brands":[{"brandId":"b1f7c2a0-1d3e-4a5b-9c8d-7e6f5a4b3c2d","name":"Acme Coffee"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/automations/{automationId}":{"get":{"operationId":"shared_automations_get","summary":"Read one automation: its settings, schedule, daily limit and last 10 runs.","description":"Read one automation: its settings, schedule, daily limit and last 10 runs.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.automations.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_automations action=get","parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: talkingObjects, miniature, textStory, quiz.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"recentRuns":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"testRun":{"type":"boolean"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsUsed":{"type":"number"},"posts":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"published":{"type":"boolean"},"link":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["published","link"],"additionalProperties":false}},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","testRun","topic","projectId","videoUrl","creditsUsed","posts","error","startedAt","completedAt"],"additionalProperties":false}}},"required":["automation","recentRuns"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Daily Quiz","format":"quiz","status":"active","pauseReason":null,"schedule":{"timezone":"America/Chicago","times":["12:00"],"videosPerDay":1},"settings":{"niche":"surprise","nicheRotation":[],"mode":"standard","questionCount":10,"timerSeconds":4,"theme":"surprise","language":"en","narration":true,"gameplay":"random","musicVolumeDb":-14,"voice":null,"music":{"mode":"library","category":"upbeat"}},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":100,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":100,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},"recentRuns":[{"id":"3e9a7c10-52bd-4f68-a1c7-8d20f4b6e913","status":"completed","testRun":false,"topic":"Why octopuses have three hearts","projectId":"c4a2d3e5-6f70-4b8c-9dae-1f2a3b4c5d6e","videoUrl":"https://media.autoclips.app/videos/example.mp4","creditsUsed":100,"posts":{},"error":null,"startedAt":"2026-11-01T09:00:00.000Z","completedAt":"2026-11-01T09:12:00.000Z"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"shared_automations_update","summary":"Change an automation's name, schedule, settings, topics or posting.","description":"Changes the parts you send; everything else stays. Changes apply from the next run. A change of what the videos are about writes new topics (it counts toward the free-AI daily limit). A change that raises what a day can spend above the daily limit, or any raise when it has none, is refused: set the limit first with set_spend_limit (409 spend_limit_needed). Switching posting on, adding a platform, changing the posting account or making YouTube more public needs the publish permission, and AI apps ask first.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.automations.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_automations action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The automation's name: unique on your account, at most 100 characters.","type":"string","minLength":1,"maxLength":100},"schedule":{"description":"When it runs. A new automation needs all three; an update changes only what you send.","type":"object","properties":{"timezone":{"description":"The time zone of the posting times (IANA, for example \"America/New_York\").","type":"string","minLength":1,"maxLength":64},"videosPerDay":{"description":"Videos a day, 1 to 3: one per posting time.","type":"integer","minimum":1,"maximum":3},"times":{"description":"The posting times, one per video a day (\"09:00\", 24-hour).","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}}},"additionalProperties":false},"talkingObjects":{"description":"A Talking Objects automation: everyday objects explain themselves.","type":"object","properties":{"objectCategories":{"description":"Which objects talk: fruits, vegetables, proteins, spices, grains, supplements, superfoods, nuts. At least one, or customCategory.","maxItems":8,"type":"array","items":{"type":"string","enum":["fruits","vegetables","proteins","spices","grains","supplements","superfoods","nuts"]}},"customCategory":{"description":"Your own objects, comma separated (\"Honey, Olive Oil\").","type":"string","minLength":1,"maxLength":500},"environment":{"description":"Where they talk: body, kitchen, garden, plate.","type":"string","enum":["body","kitchen","garden","plate"]},"model":{"description":"omniMax (Pro Max), veo31fast (Pro) or budget (Lite: a picture, a voice and animation). Priced per clip.","type":"string","enum":["omniMax","veo31fast","budget"]},"clipCount":{"description":"Clips in a video, 1 to 9. Priced per clip.","type":"integer","minimum":1,"maximum":9},"aspectRatio":{"type":"string","enum":["9:16","16:9","1:1"]},"language":{"description":"The spoken language. One the format cannot speak is refused (setting_not_allowed).","type":"string","minLength":2,"maxLength":12},"voice":{"description":"The voice, only with model budget: a voice id or name from autoclips_voices.","type":"string","minLength":1,"maxLength":120},"music":{"description":"The background music.","type":"object","properties":{"mode":{"description":"none, or library: a random track of a mood.","type":"string","enum":["none","library"]},"category":{"description":"A mood of the music library (a random track of it per video): popular, playful, sneaky, mysterious, epic, chill, upbeat, whimsical, v3-animals, v3-crime, v3-general, v3-history, v3-horror, v3-science, v3-space.","type":"string","enum":["popular","playful","sneaky","mysterious","epic","chill","upbeat","whimsical","v3-animals","v3-crime","v3-general","v3-history","v3-horror","v3-science","v3-space"]}},"required":["mode"],"additionalProperties":false},"musicVolumeDb":{"description":"The music under the video, -40 to 0 dB.","type":"number","minimum":-40,"maximum":0}},"additionalProperties":false},"miniature":{"description":"A Miniature World automation: a tilt-shift tiny world with an ambient soundscape.","type":"object","properties":{"angle":{"description":"The tiny world: rescue, farming, cooking, construction, city, custom.","type":"string","enum":["rescue","farming","cooking","construction","city","custom"]},"angleRotation":{"description":"fixed keeps the angle; rotate picks a new one each run.","type":"string","enum":["fixed","rotate"]},"storyMode":{"description":"anthology: a new tiny story every video; continuous: one world going on.","type":"string","enum":["anthology","continuous"]},"videoModel":{"description":"omniMax (Pro Max), kling3 (Pro) or veo31lite (Lite). Priced per clip.","type":"string","enum":["omniMax","kling3","veo31lite"]},"sceneCount":{"description":"Clips in a video, 4 to 8. Priced per clip.","type":"integer","minimum":4,"maximum":8},"music":{"description":"The background music.","type":"object","properties":{"mode":{"description":"none, or library: a random track of a mood.","type":"string","enum":["none","library"]},"category":{"description":"A mood of the music library (a random track of it per video): popular, playful, sneaky, mysterious, epic, chill, upbeat, whimsical, v3-animals, v3-crime, v3-general, v3-history, v3-horror, v3-science, v3-space.","type":"string","enum":["popular","playful","sneaky","mysterious","epic","chill","upbeat","whimsical","v3-animals","v3-crime","v3-general","v3-history","v3-horror","v3-science","v3-space"]}},"required":["mode"],"additionalProperties":false},"musicVolumeDb":{"description":"The music under the video, -40 to 0 dB.","type":"number","minimum":-40,"maximum":0}},"additionalProperties":false},"textStory":{"description":"A Text Story automation: a chat conversation told over gameplay.","type":"object","properties":{"category":{"description":"The kind of story: horror, revenge, drama, workplace, paranormal.","type":"string","enum":["horror","revenge","drama","workplace","paranormal"]},"categoryRotation":{"description":"fixed keeps the category; rotate goes through them.","type":"string","enum":["fixed","rotate"]},"premiseMode":{"description":"auto: a fresh premise each run; custom: premiseText.","type":"string","enum":["auto","custom"]},"premiseText":{"type":"string","minLength":1,"maxLength":1000},"language":{"description":"The spoken language. One the format cannot speak is refused (setting_not_allowed).","type":"string","minLength":2,"maxLength":12},"theme":{"description":"The chat's look: dark_blue, light_classic, amoled_green, midnight_purple, imessage_light, imessage_dark, or null for a fresh one each run.","anyOf":[{"type":"string","enum":["dark_blue","light_classic","amoled_green","midnight_purple","imessage_light","imessage_dark"]},{"type":"null"}]},"layoutMode":{"type":"string","enum":["chat_over_gameplay","full_chat"]},"gameplayCategory":{"description":"The gameplay behind the chat: minecraft, roblox, gta, subway, asmr.","type":"string","enum":["minecraft","roblox","gta","subway","asmr"]},"gameplayId":{"description":"One clip of the gameplay library, or null for a surprise.","anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"audioMode":{"description":"dual_voice, narrator or music_only. It sets the price.","type":"string","enum":["dual_voice","narrator","music_only"]},"voiceA":{"description":"The first voice: a voice id or name from autoclips_voices.","type":"string","minLength":1,"maxLength":120},"voiceB":{"description":"The second voice.","type":"string","minLength":1,"maxLength":120},"ttsModel":{"description":"null: Expressive (default); eleven_multilingual_v2: the older model.","anyOf":[{"type":"string","enum":["eleven_multilingual_v2"]},{"type":"null"}]},"lengthSeconds":{"anyOf":[{"type":"number","const":60},{"type":"number","const":75},{"type":"number","const":90},{"type":"number","const":105},{"type":"number","const":120}]},"paceSpeed":{"description":"How fast the messages come, 1 to 4.","type":"number","minimum":1,"maximum":4},"scriptMode":{"description":"The writer: normal or max. It sets the price.","type":"string","enum":["normal","max"]},"chatSounds":{"type":"boolean"},"cliffhanger":{"type":"boolean"},"music":{"description":"The background music.","type":"object","properties":{"mode":{"description":"none, or library: a random track of a mood.","type":"string","enum":["none","library"]},"category":{"description":"A mood of the music library (a random track of it per video): popular, playful, sneaky, mysterious, epic, chill, upbeat, whimsical, v3-animals, v3-crime, v3-general, v3-history, v3-horror, v3-science, v3-space.","type":"string","enum":["popular","playful","sneaky","mysterious","epic","chill","upbeat","whimsical","v3-animals","v3-crime","v3-general","v3-history","v3-horror","v3-science","v3-space"]}},"required":["mode"],"additionalProperties":false},"musicVolumeDb":{"description":"The music under the video, -40 to 0 dB.","type":"number","minimum":-40,"maximum":0}},"additionalProperties":false},"quiz":{"description":"A Quiz automation.","type":"object","properties":{"niche":{"description":"surprise rotates the packs (best: a pinned pack runs out of new questions), or one pack id.","type":"string","enum":["surprise","flags","capitals","geography-mix","countries-by-emoji","animals","animal-babies","ocean-life","dinosaurs","food","fruits-vegetables","movies-by-emoji","songs-by-emoji","history","guess-the-year","science","space","human-body","world-records","country-superlatives","inventions","mythology","sports-rules","brainrot-slang","english-vocab","phrases-by-emoji","professions-by-emoji","landmarks","everyday-objects","musical-instruments","math-teasers","odd-one-out","true-or-false-myths","would-you-rather","general-knowledge"]},"nicheRotation":{"description":"Your own list of packs to go through.","maxItems":34,"type":"array","items":{"type":"string","enum":["flags","capitals","geography-mix","countries-by-emoji","animals","animal-babies","ocean-life","dinosaurs","food","fruits-vegetables","movies-by-emoji","songs-by-emoji","history","guess-the-year","science","space","human-body","world-records","country-superlatives","inventions","mythology","sports-rules","brainrot-slang","english-vocab","phrases-by-emoji","professions-by-emoji","landmarks","everyday-objects","musical-instruments","math-teasers","odd-one-out","true-or-false-myths","would-you-rather","general-knowledge"]}},"mode":{"description":"standard, or blitz (a short under 61 seconds).","type":"string","enum":["standard","blitz"]},"questionCount":{"description":"Questions: 8 to 15 in standard, 3 to 6 in blitz.","type":"integer","minimum":3,"maximum":15},"timerSeconds":{"anyOf":[{"type":"number","const":3},{"type":"number","const":4},{"type":"number","const":5}]},"theme":{"type":"string","enum":["surprise","neon_dark","clean_light","retro_arcade","gradient_pop"]},"language":{"description":"The spoken language. One the format cannot speak is refused (setting_not_allowed).","type":"string","minLength":2,"maxLength":12},"narration":{"description":"A voice reads the questions.","type":"boolean"},"voice":{"description":"The voice: a voice id or name from autoclips_voices, or null for the language's default.","anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"gameplay":{"description":"none, random or one clip of the gameplay library.","type":"string","minLength":1,"maxLength":120},"music":{"description":"The background music.","type":"object","properties":{"mode":{"description":"none, or library: a random track of a mood.","type":"string","enum":["none","library"]},"category":{"description":"A mood of the music library (a random track of it per video): popular, playful, sneaky, mysterious, epic, chill, upbeat, whimsical, v3-animals, v3-crime, v3-general, v3-history, v3-horror, v3-science, v3-space.","type":"string","enum":["popular","playful","sneaky","mysterious","epic","chill","upbeat","whimsical","v3-animals","v3-crime","v3-general","v3-history","v3-horror","v3-science","v3-space"]}},"required":["mode"],"additionalProperties":false},"musicVolumeDb":{"description":"The music under the video, -40 to 0 dB.","type":"number","minimum":-40,"maximum":0}},"additionalProperties":false},"topics":{"description":"Where the ideas come from, and how each video ends.","type":"object","properties":{"mode":{"description":"category: ideas on a topic category; custom: ideas on your own theme.","type":"string","enum":["category","custom"]},"category":{"description":"The topic category: history, science, horror, psychology, tech, nature, money, health, weird, crime, space, food.","type":"string","enum":["history","science","horror","psychology","tech","nature","money","health","weird","crime","space","food"]},"customTopic":{"description":"Your own theme for new ideas.","type":"string","minLength":1,"maxLength":2000},"style":{"description":"The video style: engaging, educational, comedy, story, brainrot.","type":"string","enum":["engaging","educational","comedy","story","brainrot"]},"goal":{"description":"What the videos are for: views, followers, sales, awareness, custom.","type":"string","enum":["views","followers","sales","awareness","custom"]},"goalText":{"description":"Your own goal in words, with goal custom.","type":"string","minLength":1,"maxLength":500},"cta":{"description":"The call to action at the end: none, follow, subscribe, share, custom.","type":"string","enum":["none","follow","subscribe","share","custom"]},"ctaText":{"description":"Your own call to action, with cta custom.","type":"string","minLength":1,"maxLength":200},"commentWord":{"description":"The word viewers comment, with cta comment.","type":"string","minLength":1,"maxLength":40},"commentReward":{"description":"What they get for it, with cta comment.","type":"string","minLength":1,"maxLength":120},"visitUrl":{"description":"Where to send viewers, with cta visit: said in the video, never fetched.","type":"string","minLength":1,"maxLength":200}},"additionalProperties":false},"publishing":{"description":"Where each video goes. Switching posting on, changing the posting account or making YouTube videos more public needs the publish permission; only the platforms you send change.","type":"object","properties":{"email":{"description":"Email you when each video is ready.","type":"boolean"},"library":{"description":"Keep each video in My Videos.","type":"boolean"},"tiktok":{"description":"Posting to TikTok.","type":"object","properties":{"enabled":{"description":"Post every video to TikTok.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"youtube":{"description":"Posting to YouTube.","type":"object","properties":{"enabled":{"description":"Post every video to YouTube.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"},"privacy":{"description":"public, unlisted or private (default private; private videos get no comments, so no votes).","type":"string","enum":["public","unlisted","private"]},"categoryId":{"description":"The YouTube category id (2 Autos & Vehicles, 23 Comedy, 27 Education, 24 Entertainment, 1 Film & Animation, 20 Gaming, 26 Howto & Style, 10 Music, 25 News & Politics, 29 Nonprofits & Activism, 22 People & Blogs, 15 Pets & Animals, 28 Science & Technology, 17 Sports, 19 Travel & Events).","type":"string","enum":["1","2","10","15","17","19","20","22","23","24","25","26","27","28","29"]},"useAIMetadata":{"description":"Write the title and description from the video (default true).","type":"boolean"}},"required":["enabled"],"additionalProperties":false},"instagram":{"description":"Posting to Instagram.","type":"object","properties":{"enabled":{"description":"Post every video to Instagram.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"facebook":{"description":"Posting to Facebook.","type":"object","properties":{"enabled":{"description":"Post every video to Facebook.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"twitter":{"description":"Posting to X.","type":"object","properties":{"enabled":{"description":"Post every video to X.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"snapchat":{"description":"Posting to Snapchat.","type":"object","properties":{"enabled":{"description":"Post every video to Snapchat.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"example":{"schedule":{"times":["18:00"]}}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: talkingObjects, miniature, textStory, quiz.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"ideasRewritten":{"description":"True when the change writes new topics.","type":"boolean"}},"required":["automation","ideasRewritten"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Daily Quiz","format":"quiz","status":"active","pauseReason":null,"schedule":{"timezone":"America/Chicago","times":["18:00"],"videosPerDay":1},"settings":{"niche":"surprise","nicheRotation":[],"mode":"standard","questionCount":10,"timerSeconds":4,"theme":"surprise","language":"en","narration":true,"gameplay":"random","musicVolumeDb":-14,"voice":null,"music":{"mode":"library","category":"upbeat"}},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":100,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":100,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},"ideasRewritten":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"shared_automations_delete","summary":"Delete an automation and its run history. Its videos stay in My Videos.","description":"Deletes the automation and its run history. Refused while a run is being made (409 run_active: wait, or cancel_run), so no run is left without its refund.\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["Account, media and publishing"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"shared.automations.delete","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_automations action=delete","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"deleted":true,"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/automations/{automationId}/pause":{"post":{"operationId":"shared_automations_pause","summary":"Pause an automation; it makes nothing until it is resumed.","description":"Pause an automation; it makes nothing until it is resumed.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.automations.pause","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_automations action=pause","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: talkingObjects, miniature, textStory, quiz.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"changed":{"description":"False when it was already paused.","type":"boolean"}},"required":["automation","changed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Daily Quiz","format":"quiz","status":"paused","pauseReason":null,"schedule":{"timezone":"America/Chicago","times":["12:00"],"videosPerDay":1},"settings":{"niche":"surprise","nicheRotation":[],"mode":"standard","questionCount":10,"timerSeconds":4,"theme":"surprise","language":"en","narration":true,"gameplay":"random","musicVolumeDb":-14,"voice":null,"music":{"mode":"library","category":"upbeat"}},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":100,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":100,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},"changed":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/automations/{automationId}/resume":{"post":{"operationId":"shared_automations_resume","summary":"Resume a paused automation at its next posting time.","description":"Runs again from its next posting time. It needs a daily spending limit (409 spend_limit_needed: set one with set_spend_limit). Resuming an automation that posts needs the publish permission, and AI apps ask first.\n\n**Permissions:** edit, spend.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"shared.automations.resume","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_automations action=resume","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: talkingObjects, miniature, textStory, quiz.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"changed":{"description":"False when it was already active.","type":"boolean"}},"required":["automation","changed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Daily Quiz","format":"quiz","status":"active","pauseReason":null,"schedule":{"timezone":"America/Chicago","times":["12:00"],"videosPerDay":1},"settings":{"niche":"surprise","nicheRotation":[],"mode":"standard","questionCount":10,"timerSeconds":4,"theme":"surprise","language":"en","narration":true,"gameplay":"random","musicVolumeDb":-14,"voice":null,"music":{"mode":"library","category":"upbeat"}},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":100,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":100,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},"changed":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/automations/{automationId}/runs":{"post":{"operationId":"shared_automations_run_now","summary":"Make the next video of an automation now, and post it as the schedule would. Answers with a job.","description":"Makes the automation's next video right now (the app's Test button) and posts it where the automation posts. The price is the run at its most; what it does not use is given back when it is settled, and a failed run is refunded. One run at a time (409 run_in_progress), at most one every 5 minutes (429). If every posting account needs reconnecting, nothing is made or charged (409 social_token_expired). An automation that posts needs the publish permission. It answers with a job (status 202): follow it with autoclips_jobs get.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"shared.automations.run_now","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"autoclips_automations action=run_now","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"run":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}},"required":["id","status"],"additionalProperties":false},"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false}},"required":["run","job"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"run":{"id":"3e9a7c10-52bd-4f68-a1c7-8d20f4b6e913","status":"generating"},"job":{"id":"job_019a1b2c3d4e5f60718293e7","product":"shared","kind":"shared.automation_run","resource":{"type":"automation_run","id":"3e9a7c10-52bd-4f68-a1c7-8d20f4b6e913"},"status":"queued","step":"Starting the run","progress":null,"result":null,"error":null,"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","finishedAt":null,"poll_after_seconds":15}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"shared_automations_runs","summary":"List an automation's recent runs: what each made, where it posted and what it used.","description":"List an automation's recent runs: what each made, where it posted and what it used.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.automations.runs","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_automations action=runs","parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"limit","in":"query","required":false,"schema":{"description":"How many runs (1-50, default 10).","type":"integer","minimum":1,"maximum":50},"description":"How many runs (1-50, default 10).","example":5},{"name":"status","in":"query","required":false,"schema":{"description":"Only runs with this status: pending, generating, completed, failed or cancelled.","type":"string","enum":["pending","generating","completed","failed","cancelled"]},"description":"Only runs with this status: pending, generating, completed, failed or cancelled."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runs":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"testRun":{"type":"boolean"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsUsed":{"type":"number"},"posts":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"published":{"type":"boolean"},"link":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["published","link"],"additionalProperties":false}},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","testRun","topic","projectId","videoUrl","creditsUsed","posts","error","startedAt","completedAt"],"additionalProperties":false}}},"required":["runs"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"runs":[{"id":"3e9a7c10-52bd-4f68-a1c7-8d20f4b6e913","status":"completed","testRun":false,"topic":"Why octopuses have three hearts","projectId":"c4a2d3e5-6f70-4b8c-9dae-1f2a3b4c5d6e","videoUrl":"https://media.autoclips.app/videos/example.mp4","creditsUsed":100,"posts":{},"error":null,"startedAt":"2026-11-01T09:00:00.000Z","completedAt":"2026-11-01T09:12:00.000Z"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/automations/{automationId}/runs/cancel":{"post":{"operationId":"shared_automations_cancel_run","summary":"Stop the run an automation is making now. Nothing is posted.","description":"Stops the run the automation is making now (or the one runId names). What it has not used yet is given back. 404 when no run is being made.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.automations.cancel_run","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_automations action=cancel_run","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"description":"The run to stop (from runs). Left out: the one being made now.","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runId":{"anyOf":[{"type":"string"},{"type":"null"}]},"cancelled":{"type":"boolean"},"creditsRefunded":{"description":"What came back.","type":"number"}},"required":["runId","cancelled","creditsRefunded"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"runId":"3e9a7c10-52bd-4f68-a1c7-8d20f4b6e913","cancelled":true,"creditsRefunded":100}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/automations/{automationId}/spend-limit":{"put":{"operationId":"shared_automations_set_spend_limit","summary":"Set how much an automation may spend a day.","description":"Sets the daily spending limit: a run that would pass it is skipped until the next day (a run is settled after it is made, so one step's final cost can run a little over). It must allow at least one run (400 spend_limit_too_low). It resumes nothing.\n\n**Permissions:** spend.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. Short format automation day stops before a step that would go past the limit, but one step's final cost can run a little over, so the limit is not the most it can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["spend"]}],"x-autoclips-operation":"shared.automations.set_spend_limit","x-autoclips-scopes":["spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"autoclips_automations action=set_spend_limit","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"spendLimitPerDay":{"description":"The most it may spend a day, in credits (1 to 100,000). Left out: one day of runs at their most.","type":"integer","minimum":1,"maximum":100000},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["spendLimitPerDay"],"additionalProperties":false},"example":{"spendLimitPerDay":200}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: talkingObjects, miniature, textStory, quiz.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false}},"required":["automation"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Daily Quiz","format":"quiz","status":"active","pauseReason":null,"schedule":{"timezone":"America/Chicago","times":["12:00"],"videosPerDay":1},"settings":{"niche":"surprise","nicheRotation":[],"mode":"standard","questionCount":10,"timerSeconds":4,"theme":"surprise","language":"en","narration":true,"gameplay":"random","musicVolumeDb":-14,"voice":null,"music":{"mode":"library","category":"upbeat"}},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":200,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":100,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/automations":{"get":{"operationId":"ce_automations_list","summary":"List your Character Explainer automations with their settings, schedule and daily limit.","description":"List your Character Explainer automations with their settings, schedule and daily limit.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"ce.automations.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_automations action=list","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automations":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: video.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false}}},"required":["automations"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"automations":[{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Science Daily","format":"video","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["09:00"],"videosPerDay":1},"settings":{"characters":[{"character":"peter-griffin","name":"Peter Griffin","position":"bottom-left","personality":"authority"},{"character":"stewie-griffin","name":"Stewie Griffin","position":"bottom-right","personality":"comedian"}],"durationSeconds":60,"background":"random","language":"en","scriptMode":"normal","captions":true,"captionFont":"BebasNeue","aiImages":true,"aiImageModel":"webSearch","music":{"mode":"library","category":"chill"},"brand":{"brandId":null,"placement":null,"mediaMode":null}},"topics":{"mode":"category","category":"science","customTopic":null,"style":"educational","goal":"views","goalText":null,"cta":"follow","ctaText":null,"commentWord":null,"commentReward":null,"visitUrl":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":250,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":250,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"ce_automations_create","summary":"Set up a Character Explainer automation that makes and posts videos on a schedule, within a daily limit.","description":"Makes a Character Explainer automation with every option of the wizard: the cast, length, background, writer, language, captions, speech speed, scene pictures, sound effects, music, brand and watermark. At each posting time it writes a new video from your topics, and posts it. What you approve is its daily spending limit (spendLimitPerDay; left out, one day of runs at their most): a run that would pass it is skipped until the next day, and a run is settled after it is made, so one step's final cost can run a little over. A value the app would not keep for these settings is refused (400 setting_not_allowed). With publishing, every video is posted automatically: that needs the publish permission, accounts must be yours and platforms on your plan, and the approval names them. The same request again with the same Idempotency-Key hands back the same automation.\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. Character Explainer automation day stops before a step that would go past the limit, but one step's final cost can run a little over, so the limit is not the most it can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Character Explainer"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"ce.automations.create","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"ce_automations action=create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The automation's name: unique on your account, at most 100 characters.","type":"string","minLength":1,"maxLength":100},"schedule":{"description":"When it runs. A new automation needs all three; an update changes only what you send.","type":"object","properties":{"timezone":{"description":"The time zone of the posting times (IANA, for example \"America/New_York\").","type":"string","minLength":1,"maxLength":64},"videosPerDay":{"description":"Videos a day, 1 to 3: one per posting time.","type":"integer","minimum":1,"maximum":3},"times":{"description":"The posting times, one per video a day (\"09:00\", 24-hour).","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}}},"additionalProperties":false},"video":{"description":"Every video this automation makes.","type":"object","properties":{"characters":{"description":"The cast, 1 to the most the length holds (30 s: 3, 60 s: 4, 90 s: 5, 120 s: 6). A new automation needs it.","minItems":1,"maxItems":6,"type":"array","items":{"type":"object","properties":{"character":{"description":"A slug or exact name from ce_characters list: a built-in character or one of yours.","type":"string","minLength":1,"maxLength":120},"position":{"description":"Character position: Which corner a character stands in.\nChoices:\n- bottom-left — Bottom left: The character stands in the bottom left corner.\n- bottom-right — Bottom right: The character stands in the bottom right corner.\nDefault: Alternates, the first on the left (leave it out).","type":"string","enum":["bottom-left","bottom-right"]},"personality":{"description":"Character personality: The role a character plays in the conversation. Only one character is the lead (\"authority\"). When several would be, the first one you sent as \"authority\" keeps the role (if you sent none, the first one that is the lead by default), and the others become Skeptical Normies.\nChoices:\n- authority — Authority: The main character who sees the full picture, resolves tension.\n- naive-beginner — Naive Beginner: Asks basic questions everyone is thinking.\n- chaotic-zoomer — Chaotic Zoomer: Meme energy, half-informed but entertaining.\n- skeptical-normie — Skeptical Normie: Questions everything, healthy skepticism.\n- insider — Insider: Acts knowledgeable, implies hidden knowledge.\n- provocateur — Provocateur: Stirs controversy, pushes boundaries.\n- storyteller — Storyteller: Adds anecdotes, real-world examples.\n- comedian — Comedian: Turns everything into jokes, lightens mood.\n- philosopher — Philosopher: Goes deep, asks \"why\" behind everything.\n- hype-man — Hype Man: Gets excited, amplifies energy.\nDefault: The character's own default, else the lead (leave it out).","type":"string","enum":["authority","naive-beginner","chaotic-zoomer","skeptical-normie","insider","provocateur","storyteller","comedian","philosopher","hype-man"]}},"required":["character"],"additionalProperties":false}},"durationSeconds":{"description":"The length in seconds: 30, 60, 90, 120.","anyOf":[{"type":"number","const":30},{"type":"number","const":60},{"type":"number","const":90},{"type":"number","const":120}]},"background":{"description":"The gameplay behind the characters: random (default), or a clip id of the gameplay library (autoclips_options product ce, background) at least as long as the video.","type":"string","minLength":1,"maxLength":120},"scriptMode":{"description":"The writer: normal, max (Trending: looks the topic up on the web), pro (Quality) or ultra. Each costs more than the last.","type":"string","enum":["normal","max","pro","ultra"]},"language":{"description":"The spoken language (autoclips_options product ce, language). Every character in the cast must speak it.","type":"string","minLength":2,"maxLength":12},"captions":{"description":"Captions on or off.","type":"boolean"},"captionFont":{"description":"Caption font: The font of the captions.\nChoices:\n- BebasNeue — Bebas Neue: Bebas Neue lettering.\n- Anton — Anton: Anton lettering.\n- Montserrat — Montserrat: Montserrat lettering.\n- LeagueSpartan — League Spartan: League Spartan lettering.\nDefault: BebasNeue.","type":"string","enum":["BebasNeue","Anton","Montserrat","LeagueSpartan"]},"captionSize":{"description":"Caption size, 0.7 to 1.5 (1 is normal).","type":"number","minimum":0.7,"maximum":1.5},"captionVerticalPosition":{"description":"Percent from the top, 5 to 85.","type":"integer","minimum":5,"maximum":85},"captionColor":{"description":"#RRGGBB","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"captionHighlightColor":{"description":"#RRGGBB","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"captionStrokeColor":{"description":"#RRGGBB","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"speechSpeed":{"description":"How fast they speak, 0.75 to 1.5.","type":"number","minimum":0.75,"maximum":1.5},"characterFloating":{"description":"The characters float gently.","type":"boolean"},"floatingIntensity":{"description":"How much they float, 0 to 100.","type":"integer","minimum":0,"maximum":100},"characterSize":{"description":"Character size, 0.3 to 2 (1 is normal).","type":"number","minimum":0.3,"maximum":2},"aiImages":{"description":"Scene pictures between the lines (priced per scene by aiImageModel).","type":"boolean"},"aiImageModel":{"description":"The scene pictures' model: webSearch, ideogram2a, recraftV3, fluxSchnell, fluxDev, fluxPro, zImageTurbo, krea2Medium, nanoBanana2.","type":"string","enum":["webSearch","ideogram2a","recraftV3","fluxSchnell","fluxDev","fluxPro","zImageTurbo","krea2Medium","nanoBanana2"]},"aiImageStyle":{"description":"The scene pictures' style: professional, cinematic, aesthetic, educational, dramatic, graphic, meme.","type":"string","enum":["professional","cinematic","aesthetic","educational","dramatic","graphic","meme"]},"soundEffects":{"description":"Sound effects on or off.","type":"boolean"},"music":{"description":"The background music.","type":"object","properties":{"mode":{"description":"none, or library: a random track of a mood.","type":"string","enum":["none","library"]},"category":{"description":"A mood of the music library (a random track of it per video): popular, playful, sneaky, mysterious, epic, chill, upbeat, whimsical, v3-animals, v3-crime, v3-general, v3-history, v3-horror, v3-science, v3-space.","type":"string","enum":["popular","playful","sneaky","mysterious","epic","chill","upbeat","whimsical","v3-animals","v3-crime","v3-general","v3-history","v3-horror","v3-science","v3-space"]}},"required":["mode"],"additionalProperties":false},"musicVolume":{"description":"The music under the voices, 0 to 0.5.","type":"number","minimum":0,"maximum":0.5},"brand":{"description":"A brand to work into every video.","type":"object","properties":{"brandId":{"description":"One of your brands (autoclips_automations brands), or null for none.","anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"placement":{"description":"Where it is mentioned: middle or end (default end).","type":"string","enum":["middle","end"]},"mediaMode":{"description":"smart_mix, brand_only or ai_only: which pictures show (default smart_mix).","type":"string","enum":["smart_mix","brand_only","ai_only"]}},"required":["brandId"],"additionalProperties":false}},"additionalProperties":false},"topics":{"description":"Where the ideas come from, and how each video ends.","type":"object","properties":{"mode":{"description":"category: ideas on a topic category; custom: ideas on your own theme.","type":"string","enum":["category","custom"]},"category":{"description":"The topic category: history, science, horror, psychology, tech, nature, money, health, weird, crime, space, food.","type":"string","enum":["history","science","horror","psychology","tech","nature","money","health","weird","crime","space","food"]},"customTopic":{"description":"Your own theme for new ideas.","type":"string","minLength":1,"maxLength":2000},"style":{"description":"The video style: educational, comedy, story, brainrot.","type":"string","enum":["educational","comedy","story","brainrot"]},"goal":{"description":"What the videos are for: views, followers, sales, awareness, custom.","type":"string","enum":["views","followers","sales","awareness","custom"]},"goalText":{"description":"Your own goal in words, with goal custom.","type":"string","minLength":1,"maxLength":500},"cta":{"description":"The call to action at the end: follow, comment, visit, subscribe, share, custom.","type":"string","enum":["follow","comment","visit","subscribe","share","custom"]},"ctaText":{"description":"Your own call to action, with cta custom.","type":"string","minLength":1,"maxLength":200},"commentWord":{"description":"The word viewers comment, with cta comment.","type":"string","minLength":1,"maxLength":40},"commentReward":{"description":"What they get for it, with cta comment.","type":"string","minLength":1,"maxLength":120},"visitUrl":{"description":"Where to send viewers, with cta visit: said in the video, never fetched.","type":"string","minLength":1,"maxLength":200}},"additionalProperties":false},"publishing":{"description":"Where each video goes. Switching posting on, changing the posting account or making YouTube videos more public needs the publish permission; only the platforms you send change.","type":"object","properties":{"email":{"description":"Email you when each video is ready.","type":"boolean"},"library":{"description":"Keep each video in My Videos.","type":"boolean"},"tiktok":{"description":"Posting to TikTok.","type":"object","properties":{"enabled":{"description":"Post every video to TikTok.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"youtube":{"description":"Posting to YouTube.","type":"object","properties":{"enabled":{"description":"Post every video to YouTube.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"},"privacy":{"description":"public, unlisted or private (default private; private videos get no comments, so no votes).","type":"string","enum":["public","unlisted","private"]},"categoryId":{"description":"The YouTube category id (2 Autos & Vehicles, 23 Comedy, 27 Education, 24 Entertainment, 1 Film & Animation, 20 Gaming, 26 Howto & Style, 10 Music, 25 News & Politics, 29 Nonprofits & Activism, 22 People & Blogs, 15 Pets & Animals, 28 Science & Technology, 17 Sports, 19 Travel & Events).","type":"string","enum":["1","2","10","15","17","19","20","22","23","24","25","26","27","28","29"]},"useAIMetadata":{"description":"Write the title and description from the video (default true).","type":"boolean"}},"required":["enabled"],"additionalProperties":false},"instagram":{"description":"Posting to Instagram.","type":"object","properties":{"enabled":{"description":"Post every video to Instagram.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"facebook":{"description":"Posting to Facebook.","type":"object","properties":{"enabled":{"description":"Post every video to Facebook.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"twitter":{"description":"Posting to X.","type":"object","properties":{"enabled":{"description":"Post every video to X.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"snapchat":{"description":"Posting to Snapchat.","type":"object","properties":{"enabled":{"description":"Post every video to Snapchat.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false}},"additionalProperties":false},"watermarkType":{"description":"Watermark: Your text or picture on the video. Every plan.\nChoices:\n- none — None: No watermark.\n- text — Text: watermarkText.\n- image — Picture: watermarkMediaId.\nDefault: none.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"Text: The words. Default: No text (leave it out).","type":"string","minLength":1,"maxLength":50},"watermarkTextColor":{"description":"Text colour: #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundColor":{"description":"Box colour: #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundOpacity":{"description":"Box: Box, 0 (none) to 1. From 0 to 1, in steps of 0.01. Default: 0.5.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"watermarkMediaId":{"description":"A picture from autoclips_media, by id. Default: No picture (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"watermarkImageOpacity":{"description":"Picture opacity: 0.3 to 1. From 0.3 to 1, in steps of 0.01. Default: 0.7.","type":"number","minimum":0.3,"maximum":1,"multipleOf":0.01},"watermarkVerticalPosition":{"description":"Height: Percent from the top. From 10 to 90 percent. Default: 85.","type":"integer","minimum":10,"maximum":90},"watermarkHorizontalPosition":{"description":"Across: Percent from the left. From 5 to 95 percent. Default: 85.","type":"integer","minimum":5,"maximum":95},"watermarkScale":{"description":"Size: 1 is normal. From 0.5 to 3, in steps of 0.01. Default: 1.","type":"number","minimum":0.5,"maximum":3,"multipleOf":0.01},"spendLimitPerDay":{"description":"The most it may spend a day, in credits (1 to 100,000). Left out: one day of runs at their most.","type":"integer","minimum":1,"maximum":100000},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["name","schedule"],"additionalProperties":false},"example":{"name":"Science Daily","schedule":{"timezone":"America/New_York","videosPerDay":1,"times":["09:00"]},"video":{"characters":[{"character":"peter-griffin","personality":"authority"},{"character":"stewie-griffin","personality":"comedian"}],"durationSeconds":60,"scriptMode":"normal","aiImages":true,"aiImageModel":"webSearch","music":{"mode":"library","category":"chill"}},"topics":{"mode":"category","category":"science","cta":"follow"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: video.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"approvedCreditsPerDay":{"description":"The daily spending limit you approved.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["automation","approvedCreditsPerDay"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Science Daily","format":"video","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["09:00"],"videosPerDay":1},"settings":{"characters":[{"character":"peter-griffin","name":"Peter Griffin","position":"bottom-left","personality":"authority"},{"character":"stewie-griffin","name":"Stewie Griffin","position":"bottom-right","personality":"comedian"}],"durationSeconds":60,"background":"random","language":"en","scriptMode":"normal","captions":true,"captionFont":"BebasNeue","aiImages":true,"aiImageModel":"webSearch","music":{"mode":"library","category":"chill"},"brand":{"brandId":null,"placement":null,"mediaMode":null}},"topics":{"mode":"category","category":"science","customTopic":null,"style":"educational","goal":"views","goalText":null,"cta":"follow","ctaText":null,"commentWord":null,"commentReward":null,"visitUrl":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":250,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":250,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},"approvedCreditsPerDay":250}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/automations/{automationId}":{"get":{"operationId":"ce_automations_get","summary":"Read one automation: its settings, schedule, daily limit and last 10 runs.","description":"Read one automation: its settings, schedule, daily limit and last 10 runs.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"ce.automations.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_automations action=get","parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: video.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"recentRuns":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"testRun":{"type":"boolean"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsUsed":{"type":"number"},"posts":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"published":{"type":"boolean"},"link":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["published","link"],"additionalProperties":false}},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","testRun","topic","projectId","videoUrl","creditsUsed","posts","error","startedAt","completedAt"],"additionalProperties":false}}},"required":["automation","recentRuns"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Science Daily","format":"video","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["09:00"],"videosPerDay":1},"settings":{"characters":[{"character":"peter-griffin","name":"Peter Griffin","position":"bottom-left","personality":"authority"},{"character":"stewie-griffin","name":"Stewie Griffin","position":"bottom-right","personality":"comedian"}],"durationSeconds":60,"background":"random","language":"en","scriptMode":"normal","captions":true,"captionFont":"BebasNeue","aiImages":true,"aiImageModel":"webSearch","music":{"mode":"library","category":"chill"},"brand":{"brandId":null,"placement":null,"mediaMode":null}},"topics":{"mode":"category","category":"science","customTopic":null,"style":"educational","goal":"views","goalText":null,"cta":"follow","ctaText":null,"commentWord":null,"commentReward":null,"visitUrl":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":250,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":250,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},"recentRuns":[{"id":"3e9a7c10-52bd-4f68-a1c7-8d20f4b6e913","status":"completed","testRun":false,"topic":"Why octopuses have three hearts","projectId":"c4a2d3e5-6f70-4b8c-9dae-1f2a3b4c5d6e","videoUrl":"https://media.autoclips.app/videos/example.mp4","creditsUsed":250,"posts":{},"error":null,"startedAt":"2026-11-01T09:00:00.000Z","completedAt":"2026-11-01T09:12:00.000Z"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"ce_automations_update","summary":"Change an automation's name, schedule, settings, topics or posting.","description":"Changes the parts you send; everything else stays. Changes apply from the next run. A change of what the videos are about writes new topics (it counts toward the free-AI daily limit). A change that raises what a day can spend above the daily limit, or any raise when it has none, is refused: set the limit first with set_spend_limit (409 spend_limit_needed). Switching posting on, adding a platform, changing the posting account or making YouTube more public needs the publish permission, and AI apps ask first.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"ce.automations.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_automations action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The automation's name: unique on your account, at most 100 characters.","type":"string","minLength":1,"maxLength":100},"schedule":{"description":"When it runs. A new automation needs all three; an update changes only what you send.","type":"object","properties":{"timezone":{"description":"The time zone of the posting times (IANA, for example \"America/New_York\").","type":"string","minLength":1,"maxLength":64},"videosPerDay":{"description":"Videos a day, 1 to 3: one per posting time.","type":"integer","minimum":1,"maximum":3},"times":{"description":"The posting times, one per video a day (\"09:00\", 24-hour).","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}}},"additionalProperties":false},"video":{"description":"Every video this automation makes.","type":"object","properties":{"characters":{"description":"The cast, 1 to the most the length holds (30 s: 3, 60 s: 4, 90 s: 5, 120 s: 6). A new automation needs it.","minItems":1,"maxItems":6,"type":"array","items":{"type":"object","properties":{"character":{"description":"A slug or exact name from ce_characters list: a built-in character or one of yours.","type":"string","minLength":1,"maxLength":120},"position":{"description":"Character position: Which corner a character stands in.\nChoices:\n- bottom-left — Bottom left: The character stands in the bottom left corner.\n- bottom-right — Bottom right: The character stands in the bottom right corner.\nDefault: Alternates, the first on the left (leave it out).","type":"string","enum":["bottom-left","bottom-right"]},"personality":{"description":"Character personality: The role a character plays in the conversation. Only one character is the lead (\"authority\"). When several would be, the first one you sent as \"authority\" keeps the role (if you sent none, the first one that is the lead by default), and the others become Skeptical Normies.\nChoices:\n- authority — Authority: The main character who sees the full picture, resolves tension.\n- naive-beginner — Naive Beginner: Asks basic questions everyone is thinking.\n- chaotic-zoomer — Chaotic Zoomer: Meme energy, half-informed but entertaining.\n- skeptical-normie — Skeptical Normie: Questions everything, healthy skepticism.\n- insider — Insider: Acts knowledgeable, implies hidden knowledge.\n- provocateur — Provocateur: Stirs controversy, pushes boundaries.\n- storyteller — Storyteller: Adds anecdotes, real-world examples.\n- comedian — Comedian: Turns everything into jokes, lightens mood.\n- philosopher — Philosopher: Goes deep, asks \"why\" behind everything.\n- hype-man — Hype Man: Gets excited, amplifies energy.\nDefault: The character's own default, else the lead (leave it out).","type":"string","enum":["authority","naive-beginner","chaotic-zoomer","skeptical-normie","insider","provocateur","storyteller","comedian","philosopher","hype-man"]}},"required":["character"],"additionalProperties":false}},"durationSeconds":{"description":"The length in seconds: 30, 60, 90, 120.","anyOf":[{"type":"number","const":30},{"type":"number","const":60},{"type":"number","const":90},{"type":"number","const":120}]},"background":{"description":"The gameplay behind the characters: random (default), or a clip id of the gameplay library (autoclips_options product ce, background) at least as long as the video.","type":"string","minLength":1,"maxLength":120},"scriptMode":{"description":"The writer: normal, max (Trending: looks the topic up on the web), pro (Quality) or ultra. Each costs more than the last.","type":"string","enum":["normal","max","pro","ultra"]},"language":{"description":"The spoken language (autoclips_options product ce, language). Every character in the cast must speak it.","type":"string","minLength":2,"maxLength":12},"captions":{"description":"Captions on or off.","type":"boolean"},"captionFont":{"description":"Caption font: The font of the captions.\nChoices:\n- BebasNeue — Bebas Neue: Bebas Neue lettering.\n- Anton — Anton: Anton lettering.\n- Montserrat — Montserrat: Montserrat lettering.\n- LeagueSpartan — League Spartan: League Spartan lettering.\nDefault: BebasNeue.","type":"string","enum":["BebasNeue","Anton","Montserrat","LeagueSpartan"]},"captionSize":{"description":"Caption size, 0.7 to 1.5 (1 is normal).","type":"number","minimum":0.7,"maximum":1.5},"captionVerticalPosition":{"description":"Percent from the top, 5 to 85.","type":"integer","minimum":5,"maximum":85},"captionColor":{"description":"#RRGGBB","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"captionHighlightColor":{"description":"#RRGGBB","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"captionStrokeColor":{"description":"#RRGGBB","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"speechSpeed":{"description":"How fast they speak, 0.75 to 1.5.","type":"number","minimum":0.75,"maximum":1.5},"characterFloating":{"description":"The characters float gently.","type":"boolean"},"floatingIntensity":{"description":"How much they float, 0 to 100.","type":"integer","minimum":0,"maximum":100},"characterSize":{"description":"Character size, 0.3 to 2 (1 is normal).","type":"number","minimum":0.3,"maximum":2},"aiImages":{"description":"Scene pictures between the lines (priced per scene by aiImageModel).","type":"boolean"},"aiImageModel":{"description":"The scene pictures' model: webSearch, ideogram2a, recraftV3, fluxSchnell, fluxDev, fluxPro, zImageTurbo, krea2Medium, nanoBanana2.","type":"string","enum":["webSearch","ideogram2a","recraftV3","fluxSchnell","fluxDev","fluxPro","zImageTurbo","krea2Medium","nanoBanana2"]},"aiImageStyle":{"description":"The scene pictures' style: professional, cinematic, aesthetic, educational, dramatic, graphic, meme.","type":"string","enum":["professional","cinematic","aesthetic","educational","dramatic","graphic","meme"]},"soundEffects":{"description":"Sound effects on or off.","type":"boolean"},"music":{"description":"The background music.","type":"object","properties":{"mode":{"description":"none, or library: a random track of a mood.","type":"string","enum":["none","library"]},"category":{"description":"A mood of the music library (a random track of it per video): popular, playful, sneaky, mysterious, epic, chill, upbeat, whimsical, v3-animals, v3-crime, v3-general, v3-history, v3-horror, v3-science, v3-space.","type":"string","enum":["popular","playful","sneaky","mysterious","epic","chill","upbeat","whimsical","v3-animals","v3-crime","v3-general","v3-history","v3-horror","v3-science","v3-space"]}},"required":["mode"],"additionalProperties":false},"musicVolume":{"description":"The music under the voices, 0 to 0.5.","type":"number","minimum":0,"maximum":0.5},"brand":{"description":"A brand to work into every video.","type":"object","properties":{"brandId":{"description":"One of your brands (autoclips_automations brands), or null for none.","anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"placement":{"description":"Where it is mentioned: middle or end (default end).","type":"string","enum":["middle","end"]},"mediaMode":{"description":"smart_mix, brand_only or ai_only: which pictures show (default smart_mix).","type":"string","enum":["smart_mix","brand_only","ai_only"]}},"required":["brandId"],"additionalProperties":false}},"additionalProperties":false},"topics":{"description":"Where the ideas come from, and how each video ends.","type":"object","properties":{"mode":{"description":"category: ideas on a topic category; custom: ideas on your own theme.","type":"string","enum":["category","custom"]},"category":{"description":"The topic category: history, science, horror, psychology, tech, nature, money, health, weird, crime, space, food.","type":"string","enum":["history","science","horror","psychology","tech","nature","money","health","weird","crime","space","food"]},"customTopic":{"description":"Your own theme for new ideas.","type":"string","minLength":1,"maxLength":2000},"style":{"description":"The video style: educational, comedy, story, brainrot.","type":"string","enum":["educational","comedy","story","brainrot"]},"goal":{"description":"What the videos are for: views, followers, sales, awareness, custom.","type":"string","enum":["views","followers","sales","awareness","custom"]},"goalText":{"description":"Your own goal in words, with goal custom.","type":"string","minLength":1,"maxLength":500},"cta":{"description":"The call to action at the end: follow, comment, visit, subscribe, share, custom.","type":"string","enum":["follow","comment","visit","subscribe","share","custom"]},"ctaText":{"description":"Your own call to action, with cta custom.","type":"string","minLength":1,"maxLength":200},"commentWord":{"description":"The word viewers comment, with cta comment.","type":"string","minLength":1,"maxLength":40},"commentReward":{"description":"What they get for it, with cta comment.","type":"string","minLength":1,"maxLength":120},"visitUrl":{"description":"Where to send viewers, with cta visit: said in the video, never fetched.","type":"string","minLength":1,"maxLength":200}},"additionalProperties":false},"publishing":{"description":"Where each video goes. Switching posting on, changing the posting account or making YouTube videos more public needs the publish permission; only the platforms you send change.","type":"object","properties":{"email":{"description":"Email you when each video is ready.","type":"boolean"},"library":{"description":"Keep each video in My Videos.","type":"boolean"},"tiktok":{"description":"Posting to TikTok.","type":"object","properties":{"enabled":{"description":"Post every video to TikTok.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"youtube":{"description":"Posting to YouTube.","type":"object","properties":{"enabled":{"description":"Post every video to YouTube.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"},"privacy":{"description":"public, unlisted or private (default private; private videos get no comments, so no votes).","type":"string","enum":["public","unlisted","private"]},"categoryId":{"description":"The YouTube category id (2 Autos & Vehicles, 23 Comedy, 27 Education, 24 Entertainment, 1 Film & Animation, 20 Gaming, 26 Howto & Style, 10 Music, 25 News & Politics, 29 Nonprofits & Activism, 22 People & Blogs, 15 Pets & Animals, 28 Science & Technology, 17 Sports, 19 Travel & Events).","type":"string","enum":["1","2","10","15","17","19","20","22","23","24","25","26","27","28","29"]},"useAIMetadata":{"description":"Write the title and description from the video (default true).","type":"boolean"}},"required":["enabled"],"additionalProperties":false},"instagram":{"description":"Posting to Instagram.","type":"object","properties":{"enabled":{"description":"Post every video to Instagram.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"facebook":{"description":"Posting to Facebook.","type":"object","properties":{"enabled":{"description":"Post every video to Facebook.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"twitter":{"description":"Posting to X.","type":"object","properties":{"enabled":{"description":"Post every video to X.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"snapchat":{"description":"Posting to Snapchat.","type":"object","properties":{"enabled":{"description":"Post every video to Snapchat.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false}},"additionalProperties":false},"watermarkType":{"description":"Watermark: Your text or picture on the video. Every plan.\nChoices:\n- none — None: No watermark.\n- text — Text: watermarkText.\n- image — Picture: watermarkMediaId.\nDefault: none.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"Text: The words. Default: No text (leave it out).","type":"string","minLength":1,"maxLength":50},"watermarkTextColor":{"description":"Text colour: #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundColor":{"description":"Box colour: #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundOpacity":{"description":"Box: Box, 0 (none) to 1. From 0 to 1, in steps of 0.01. Default: 0.5.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"watermarkMediaId":{"description":"A picture from autoclips_media, by id. Default: No picture (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"watermarkImageOpacity":{"description":"Picture opacity: 0.3 to 1. From 0.3 to 1, in steps of 0.01. Default: 0.7.","type":"number","minimum":0.3,"maximum":1,"multipleOf":0.01},"watermarkVerticalPosition":{"description":"Height: Percent from the top. From 10 to 90 percent. Default: 85.","type":"integer","minimum":10,"maximum":90},"watermarkHorizontalPosition":{"description":"Across: Percent from the left. From 5 to 95 percent. Default: 85.","type":"integer","minimum":5,"maximum":95},"watermarkScale":{"description":"Size: 1 is normal. From 0.5 to 3, in steps of 0.01. Default: 1.","type":"number","minimum":0.5,"maximum":3,"multipleOf":0.01}},"additionalProperties":false},"example":{"schedule":{"times":["18:00"]}}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: video.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"ideasRewritten":{"description":"True when the change writes new topics.","type":"boolean"}},"required":["automation","ideasRewritten"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Science Daily","format":"video","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["18:00"],"videosPerDay":1},"settings":{"characters":[{"character":"peter-griffin","name":"Peter Griffin","position":"bottom-left","personality":"authority"},{"character":"stewie-griffin","name":"Stewie Griffin","position":"bottom-right","personality":"comedian"}],"durationSeconds":60,"background":"random","language":"en","scriptMode":"normal","captions":true,"captionFont":"BebasNeue","aiImages":true,"aiImageModel":"webSearch","music":{"mode":"library","category":"chill"},"brand":{"brandId":null,"placement":null,"mediaMode":null}},"topics":{"mode":"category","category":"science","customTopic":null,"style":"educational","goal":"views","goalText":null,"cta":"follow","ctaText":null,"commentWord":null,"commentReward":null,"visitUrl":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":250,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":250,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},"ideasRewritten":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"ce_automations_delete","summary":"Delete an automation and its run history. Its videos stay in My Videos.","description":"Deletes the automation and its run history. Refused while a run is being made (409 run_active: wait, or cancel_run), so no run is left without its refund.\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["Character Explainer"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"ce.automations.delete","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_automations action=delete","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"deleted":true,"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/automations/{automationId}/pause":{"post":{"operationId":"ce_automations_pause","summary":"Pause an automation; it makes nothing until it is resumed.","description":"Pause an automation; it makes nothing until it is resumed.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"ce.automations.pause","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_automations action=pause","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: video.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"changed":{"description":"False when it was already paused.","type":"boolean"}},"required":["automation","changed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Science Daily","format":"video","status":"paused","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["09:00"],"videosPerDay":1},"settings":{"characters":[{"character":"peter-griffin","name":"Peter Griffin","position":"bottom-left","personality":"authority"},{"character":"stewie-griffin","name":"Stewie Griffin","position":"bottom-right","personality":"comedian"}],"durationSeconds":60,"background":"random","language":"en","scriptMode":"normal","captions":true,"captionFont":"BebasNeue","aiImages":true,"aiImageModel":"webSearch","music":{"mode":"library","category":"chill"},"brand":{"brandId":null,"placement":null,"mediaMode":null}},"topics":{"mode":"category","category":"science","customTopic":null,"style":"educational","goal":"views","goalText":null,"cta":"follow","ctaText":null,"commentWord":null,"commentReward":null,"visitUrl":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":250,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":250,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},"changed":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/automations/{automationId}/resume":{"post":{"operationId":"ce_automations_resume","summary":"Resume a paused automation at its next posting time.","description":"Runs again from its next posting time. It needs a daily spending limit (409 spend_limit_needed: set one with set_spend_limit). Resuming an automation that posts needs the publish permission, and AI apps ask first.\n\n**Permissions:** edit, spend.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"ce.automations.resume","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_automations action=resume","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: video.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"changed":{"description":"False when it was already active.","type":"boolean"}},"required":["automation","changed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Science Daily","format":"video","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["09:00"],"videosPerDay":1},"settings":{"characters":[{"character":"peter-griffin","name":"Peter Griffin","position":"bottom-left","personality":"authority"},{"character":"stewie-griffin","name":"Stewie Griffin","position":"bottom-right","personality":"comedian"}],"durationSeconds":60,"background":"random","language":"en","scriptMode":"normal","captions":true,"captionFont":"BebasNeue","aiImages":true,"aiImageModel":"webSearch","music":{"mode":"library","category":"chill"},"brand":{"brandId":null,"placement":null,"mediaMode":null}},"topics":{"mode":"category","category":"science","customTopic":null,"style":"educational","goal":"views","goalText":null,"cta":"follow","ctaText":null,"commentWord":null,"commentReward":null,"visitUrl":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":250,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":250,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},"changed":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/automations/{automationId}/runs":{"post":{"operationId":"ce_automations_run_now","summary":"Make the next video of an automation now, and post it as the schedule would. Answers with a job.","description":"Makes the automation's next video right now (the app's Test button) and posts it where the automation posts. The price is the run at its most; what it does not use is given back when it is settled, and a failed run is refunded. One run at a time (409 run_in_progress), at most one every 5 minutes (429). If every posting account needs reconnecting, nothing is made or charged (409 social_token_expired). An automation that posts needs the publish permission. It answers with a job (status 202): follow it with autoclips_jobs get.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Character Explainer"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"ce.automations.run_now","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"ce_automations action=run_now","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"run":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}},"required":["id","status"],"additionalProperties":false},"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false}},"required":["run","job"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"run":{"id":"3e9a7c10-52bd-4f68-a1c7-8d20f4b6e913","status":"generating"},"job":{"id":"job_019a1b2c3d4e5f60718293e7","product":"ce","kind":"ce.automation_run","resource":{"type":"automation_run","id":"3e9a7c10-52bd-4f68-a1c7-8d20f4b6e913"},"status":"queued","step":"Starting the run","progress":null,"result":null,"error":null,"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","finishedAt":null,"poll_after_seconds":15}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"ce_automations_runs","summary":"List an automation's recent runs: what each made, where it posted and what it used.","description":"List an automation's recent runs: what each made, where it posted and what it used.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"ce.automations.runs","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_automations action=runs","parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"limit","in":"query","required":false,"schema":{"description":"How many runs (1-50, default 10).","type":"integer","minimum":1,"maximum":50},"description":"How many runs (1-50, default 10).","example":5},{"name":"status","in":"query","required":false,"schema":{"description":"Only runs with this status: pending, generating, completed, failed or cancelled.","type":"string","enum":["pending","generating","completed","failed","cancelled"]},"description":"Only runs with this status: pending, generating, completed, failed or cancelled."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runs":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"testRun":{"type":"boolean"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsUsed":{"type":"number"},"posts":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"published":{"type":"boolean"},"link":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["published","link"],"additionalProperties":false}},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","testRun","topic","projectId","videoUrl","creditsUsed","posts","error","startedAt","completedAt"],"additionalProperties":false}}},"required":["runs"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"runs":[{"id":"3e9a7c10-52bd-4f68-a1c7-8d20f4b6e913","status":"completed","testRun":false,"topic":"Why octopuses have three hearts","projectId":"c4a2d3e5-6f70-4b8c-9dae-1f2a3b4c5d6e","videoUrl":"https://media.autoclips.app/videos/example.mp4","creditsUsed":250,"posts":{},"error":null,"startedAt":"2026-11-01T09:00:00.000Z","completedAt":"2026-11-01T09:12:00.000Z"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/automations/{automationId}/runs/cancel":{"post":{"operationId":"ce_automations_cancel_run","summary":"Stop the run an automation is making now. Nothing is posted.","description":"Stops the run the automation is making now (or the one runId names). What it has not used yet is given back. 404 when no run is being made.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"ce.automations.cancel_run","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_automations action=cancel_run","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"description":"The run to stop (from runs). Left out: the one being made now.","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runId":{"anyOf":[{"type":"string"},{"type":"null"}]},"cancelled":{"type":"boolean"},"creditsRefunded":{"description":"What came back.","type":"number"}},"required":["runId","cancelled","creditsRefunded"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"runId":"3e9a7c10-52bd-4f68-a1c7-8d20f4b6e913","cancelled":true,"creditsRefunded":250}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/automations/{automationId}/spend-limit":{"put":{"operationId":"ce_automations_set_spend_limit","summary":"Set how much an automation may spend a day.","description":"Sets the daily spending limit: a run that would pass it is skipped until the next day (a run is settled after it is made, so one step's final cost can run a little over). It must allow at least one run (400 spend_limit_too_low). It resumes nothing.\n\n**Permissions:** spend.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. Character Explainer automation day stops before a step that would go past the limit, but one step's final cost can run a little over, so the limit is not the most it can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Character Explainer"],"security":[{"bearerAuth":["spend"]}],"x-autoclips-operation":"ce.automations.set_spend_limit","x-autoclips-scopes":["spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"ce_automations action=set_spend_limit","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"spendLimitPerDay":{"description":"The most it may spend a day, in credits (1 to 100,000). Left out: one day of runs at their most.","type":"integer","minimum":1,"maximum":100000},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["spendLimitPerDay"],"additionalProperties":false},"example":{"spendLimitPerDay":500}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: video.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false}},"required":["automation"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Science Daily","format":"video","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["09:00"],"videosPerDay":1},"settings":{"characters":[{"character":"peter-griffin","name":"Peter Griffin","position":"bottom-left","personality":"authority"},{"character":"stewie-griffin","name":"Stewie Griffin","position":"bottom-right","personality":"comedian"}],"durationSeconds":60,"background":"random","language":"en","scriptMode":"normal","captions":true,"captionFont":"BebasNeue","aiImages":true,"aiImageModel":"webSearch","music":{"mode":"library","category":"chill"},"brand":{"brandId":null,"placement":null,"mediaMode":null}},"topics":{"mode":"category","category":"science","customTopic":null,"style":"educational","goal":"views","goalText":null,"cta":"follow","ctaText":null,"commentWord":null,"commentReward":null,"visitUrl":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":500,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":250,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/characters":{"get":{"operationId":"ce_characters_list","summary":"The characters you can cast: the app's built-in ones and your own, with the languages each can speak.","description":"Lists the characters a Character Explainer video can star, the app's built-in ones first, then your own. Filter with language (only characters that can speak it) and type (built_in or mine). Send a character's slug in characters of ce_projects create or update. Voices and their recordings are never shown.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"ce.characters.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_characters action=list","parameters":[{"name":"language","in":"query","required":false,"schema":{"description":"Only characters that can speak this language: a language code from autoclips_options (product ce, option language), for example es. Default: every language (leave it out).","type":"string","enum":["en","es","pt","fr","de","hi","ar","ja","zh","id","ru","tr","ko","it","nl","pl","ro","cs","sk","hu","sv","da","no","fi","is","et","lv","lt","el","bg","uk","be","mk","sr","hr","bs","sl","ca","gl","ast","oc","ga","cy","lb","mt","bn","ur","ta","te","mr","gu","kn","ml","pa","or","as","ne","sd","ps","fa","he","ckb","yue","vi","th","lo","my","ms","fil","ceb","jv","mn","kk","ky","uz","tg","az","hy","ka","sw","ha","yo","so","af","ln","am","ny","ff","kam","lg","sn","wo","zu","mi"]},"description":"Only characters that can speak this language: a language code from autoclips_options (product ce, option language), for example es. Default: every language (leave it out).","example":"es"},{"name":"type","in":"query","required":false,"schema":{"description":"built_in: only the app's characters; mine: only the ones you made. Default: both (leave it out).","type":"string","enum":["built_in","mine"]},"description":"built_in: only the app's characters; mine: only the ones you made. Default: both (leave it out).","example":"mine"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"characters":{"type":"array","items":{"type":"object","properties":{"slug":{"description":"What to send as character in ce_projects create or update.","type":"string"},"name":{"type":"string"},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"builtIn":{"description":"One of the app's characters.","type":"boolean"},"yours":{"description":"A character you made.","type":"boolean"},"pictureUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"languages":{"description":"The languages this character can speak (language codes).","type":"array","items":{"type":"string"}},"defaultPersonality":{"description":"Its usual role, when you do not pick one. A video has one lead (authority): when another character already leads, a character whose usual role is the lead plays a supporting role instead (Skeptical Normie, or another one nobody has yet).","type":"string"}},"required":["slug","name","category","builtIn","yours","pictureUrl","languages","defaultPersonality"],"additionalProperties":false}},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["characters","count"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"characters":[{"slug":"peter-griffin","name":"Peter Griffin","category":"family-guy","builtIn":true,"yours":false,"pictureUrl":"https://media.autoclips.app/character-references/base-characters/peter-griffin.webp","languages":["en"],"defaultPersonality":"authority"},{"slug":"custom-ms-rivera-1a2b3c4d","name":"Ms Rivera","category":"custom","builtIn":false,"yours":true,"pictureUrl":"https://media.autoclips.app/character-references/example-user/custom_character_rivera.png","languages":["en","es","pt","fr","de","hi","ar","ja","zh","id","ru","tr","ko","it","nl","pl","ro","cs","sk","hu","sv","da","no","fi","is","et","lv","lt","el","bg","uk","be","mk","sr","hr","bs","sl","ca","gl","ast","oc","ga","cy","lb","mt","bn","ur","ta","te","mr","gu","kn","ml","pa","or","as","ne","sd","ps","fa","he","ckb","yue","vi","th","lo","my","ms","fil","ceb","jv","mn","kk","ky","uz","tg","az","hy","ka","sw","ha","yo","so","af","ln","am","ny","ff","kam","lg","sn","wo","zu","mi"],"defaultPersonality":"authority"}],"count":2}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/ideas":{"get":{"operationId":"ce_ideas_list","summary":"Today's topic ideas for a Character Explainer video, the ones the app suggests. Free.","description":"The topic ideas the app suggests on its create page: picked each day from what is in the news, with why each is worth a video. today says whether they are today's. When today's list is not ready you get ideas that always work (kind evergreen). Use one as the topic of ce_projects create.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"ce.ideas.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_projects action=ideas","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ideas":{"type":"array","items":{"type":"object","properties":{"label":{"description":"The idea, ready to use as the topic of ce_projects create.","type":"string"},"category":{"description":"What kind of story it is (news, tech, …).","anyOf":[{"type":"string"},{"type":"null"}]},"why":{"description":"Why it is worth a video today.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["label","category","why"],"additionalProperties":false}},"kind":{"description":"trending: picked from the news; evergreen: ideas that always work, when the daily list is not ready.","type":"string","enum":["trending","evergreen"]},"today":{"description":"Whether the trending ideas are today's.","type":"boolean"},"day":{"description":"The day the trending ideas were picked (YYYY-MM-DD).","anyOf":[{"type":"string"},{"type":"null"}]},"note":{"type":"string"}},"required":["ideas","kind","today","day","note"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"ideas":[{"label":"Why Your Phone Battery Dies Faster in the Cold","category":"tech","why":"A cold snap this week has people asking why their phones shut off at 30 percent."},{"label":"How a Tiny Asteroid Lit Up the Sky Over Europe","category":"news","why":"Videos of last night's fireball are everywhere today."}],"kind":"trending","today":true,"day":"2026-10-12","note":"Ideas picked from what is in the news today. Use one as the topic of ce_projects create."}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/projects":{"post":{"operationId":"ce_projects_create","summary":"Make a free Character Explainer draft from a topic or your own script, with its characters and settings.","description":"Makes a draft project, the way the app's wizard starts one. Send a topic (or inputMode custom_script with your own script in customScript) and 1 to 6 characters by slug (ce_characters list shows them: the built-in ones and your own). A longer video holds more characters: up to 3 for 30 seconds, 4 for 1 minute, 5 for 1.5 minutes and 6 for 2 minutes or more. Every character must be able to speak the language: ce_characters list says which languages each one speaks (the built-in characters speak English).\nLeave the other settings out for the wizard's new-project choices (Explainer, 30 seconds, speech speed 1.15, voice emotion Off, a Minecraft clip that fits, no music, your account's voice model). Every option, with its price, is in autoclips_options (product ce).\nFree plans make 30-second videos, paid for from the 150 credits a new account gets, and every free video carries a small \"Made with Autoclips.app\" badge. A longer length is set to 30 seconds, and the note says so with the way to a longer video; your own script, the Trending, Quality and Ultra scripts, motion graphics and an outro need a paid plan.\nNo script is written and nothing is charged yet. The answer shows what rendering the video will cost (price). Next: write the script with ce_script generate.\nSending the same request again with the same Idempotency-Key hands back the same draft.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"ce.projects.create","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_projects action=create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputMode":{"description":"What the script comes from: Write the script from a topic, or use a script you paste.\nChoices:\n- topic — Topic: The AI writes the script from your topic.\n- custom_script — Your script: Your own script, split into scenes and voiced as written. (Billed at the longer of the length you pick and how long your script takes to say (about 500 characters per 30 seconds; speaker names are not counted); plans: paid)\nDefault: topic.","type":"string","enum":["topic","custom_script"]},"topic":{"description":"Topic: What the video is about, in your words (research notes and links are fine). A web link in it is read from the web while the script is written; a link to a private or internal address is refused. No default: ask the user.","type":"string","minLength":1,"maxLength":5000},"customScript":{"description":"Your script: The script to use, for \"Your script\" (inputMode custom_script). It sets the billed length: about 500 spoken characters per 30 seconds, never less than the length you pick. Speaker names (\"Peter:\"), markdown and blank lines are not counted; Japanese, Chinese, Thai and Korean count at their own speaking pace, and a script that takes longer than 5 minutes to say is refused. Default: No pasted script (leave it out).","type":"string","minLength":20,"maxLength":5000},"style":{"description":"Style: How the script is written.\nChoices:\n- explainer — Explainer: Show how something really works.\n- controversy — Controversy: Lay out a case, exhibit by exhibit.\n- educational — Educational: Teach something new.\n- funny — Comedy: Make them laugh.\n- storytelling — Story: Tell a story.\n- brainrot — Brain Rot: Gen Z chaos mode: fast, loud and full of slang.\nDefault: explainer.","type":"string","enum":["explainer","controversy","educational","funny","storytelling","brainrot"]},"durationSeconds":{"description":"How long the video is meant to be. It is billed at the price band it rounds up to (30, 60, 90, 120, 180 or 300 seconds): a 40-second video costs what a 1-minute one does. Free plans make 30-second videos: a longer length is set to 30 seconds, with a note. Send it as a number (60); its id as text (\"60\") is taken too. One of 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 180, 240, 300 seconds. Default: 30.","anyOf":[{"type":"number","enum":[30,40,50,60,70,80,90,100,110,120,180,240,300]},{"type":"string","pattern":"^(?:30|40|50|60|70|80|90|100|110|120|180|240|300)$"}]},"language":{"title":"Language (Character Explainer option language)","description":"Language: The language of the script, the voices and the captions. Every character in the video must be able to speak it (ce_characters list shows which can).\nOne of 94 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=ce&option=language) to see them all.\nChoices:\n- en — English: English script, voices and captions.\n- es — Spanish: Spanish script, voices and captions.\n- pt — Portuguese: Portuguese script, voices and captions.\n- fr — French: French script, voices and captions.\n- de — German: German script, voices and captions.\n- hi — Hindi: Hindi script, voices and captions.\n- ar — Arabic: Arabic script, voices and captions.\n- ja — Japanese: Japanese script, voices and captions.\n- zh — Chinese: Chinese script, voices and captions.\n- id — Indonesian: Indonesian script, voices and captions.\n- ru — Russian: Russian script, voices and captions.\n- tr — Turkish: Turkish script, voices and captions.\n- ko — Korean: Korean script, voices and captions.\n- it — Italian: Italian script, voices and captions.\n- nl — Dutch: Dutch script, voices and captions.\n- pl — Polish: Polish script, voices and captions.\n- ro — Romanian: Romanian script, voices and captions.\n- cs — Czech: Czech script, voices and captions.\n- sk — Slovak: Slovak script, voices and captions.\n- hu — Hungarian: Hungarian script, voices and captions.\n- sv — Swedish: Swedish script, voices and captions.\n- da — Danish: Danish script, voices and captions.\n- no — Norwegian: Norwegian script, voices and captions.\n- fi — Finnish: Finnish script, voices and captions.\n- is — Icelandic: Icelandic script, voices and captions.\n- et — Estonian: Estonian script, voices and captions.\n- lv — Latvian: Latvian script, voices and captions.\n- lt — Lithuanian: Lithuanian script, voices and captions.\n- el — Greek: Greek script, voices and captions.\n- bg — Bulgarian: Bulgarian script, voices and captions.\n…and 64 more.\nDefault: en.","type":"string"},"scriptMode":{"description":"Script quality: Which writer makes the script. It sets the video price, by length.\nChoices:\n- normal — Normal: Quick, solid scripts for subjects that do not change: how-tos, explainers, timeless facts. (50 (30 seconds), 50 (1 minute), 100 (1.5 minutes), 200 (2 minutes), 300 (3 minutes), 500 (5 minutes) credits)\n- max — Trending: Looks the topic up on the web as it writes, so it can use real facts from this week. For news, launches and anything happening right now. (100 (30 seconds), 100 (1 minute), 200 (1.5 minutes), 300 (2 minutes), 450 (3 minutes), 750 (5 minutes) credits; plans: paid)\n- pro — Quality: The most polished writing: stronger hooks, better pacing, endings that land. No web search. (100 (30 seconds), 100 (1 minute), 200 (1.5 minutes), 300 (2 minutes), 450 (3 minutes), 750 (5 minutes) credits; plans: paid)\n- ultra — Ultra: The strongest writing plus live web research: the best script we can make, whatever the topic. (200 (30 seconds), 200 (1 minute), 300 (1.5 minutes), 400 (2 minutes), 600 (3 minutes), 1000 (5 minutes) credits; plans: paid)\nDefault: normal.","type":"string","enum":["normal","max","pro","ultra"]},"customInstructions":{"description":"Extra instructions: Anything the writer should keep in mind (tone, audience, a call to action). The wizard has no box for it; automations and the original AI tool use it. Default: None (leave it out).","type":"string","minLength":1,"maxLength":1000},"characterPlacementX":{"description":"Character placement, across: Where the character stands, in percent of the frame from the left, when you move it off its corner (the Preview step's Move character). Send it with characterPlacementY. An update that sends null for both characterPlacementX and characterPlacementY puts the character back in its corner. From 5 to 95 percent. Default: The character's corner (leave it out).","type":"integer","minimum":5,"maximum":95},"characterPlacementY":{"description":"Character placement, down: Where the character stands, in percent of the frame from the top. Send it with characterPlacementX. An update that sends null for both characterPlacementX and characterPlacementY puts the character back in its corner. From 20 to 100 percent. Default: The character's corner (leave it out).","type":"integer","minimum":20,"maximum":100},"characterSizeMultiplier":{"description":"Character size: How big the characters are on screen: 1 is normal, 0.3 is 30 percent, 2 is double. From 0.3 to 2, in steps of 0.05. Default: 1.","type":"number","minimum":0.3,"maximum":2,"multipleOf":0.05},"characterFloating":{"description":"Floating characters: A smooth idle wobble on the characters. Default: false.","type":"boolean"},"floatingIntensity":{"description":"Floating strength: How strong the wobble is, from subtle (0) to dramatic (100). Used when floating is on. From 0 to 100 percent, in steps of 5. Default: 50.","type":"integer","minimum":0,"maximum":100,"multipleOf":5},"ttsModel":{"description":"Voice model: Which voice model speaks the lines. A new project starts on your account's voice model (the one you last picked in the app, shared with V3), or Eleven v4 if you never picked one.\nChoices:\n- eleven_v4 — Eleven v4: Recommended. The newest model, best for every language.\n- eleven_v3 — Eleven v3: An older model. Some cloned cartoon voices sound more natural on it.\n- eleven_multilingual_v2 — Multilingual v2: An older model with a steady read. What Character Explainer spoke before.\nDefault: your account's voice model (leave it out).","type":"string","enum":["eleven_v4","eleven_v3","eleven_multilingual_v2"]},"voiceEmotion":{"description":"Voice emotion: How much emotion the voices carry.\nChoices:\n- off — Off: A neutral, steady tone throughout.\n- subtle — Subtle: Light emotion: hooks sound a little more engaging.\n- normal — Normal: Emotion from the context: hooks are exciting, questions are curious.\n- expressive — Expressive: Strong emotion, for entertainment and comedy.\nDefault: off.","type":"string","enum":["off","subtle","normal","expressive"]},"speechSpeed":{"description":"Speech speed: How fast the characters talk: 1 is normal, 1.15 is a little quicker for better pacing. From 0.75 to 1.5, in steps of 0.05. Default: 1.15.","type":"number","minimum":0.75,"maximum":1.5,"multipleOf":0.05},"overrideSpeechSpeed":{"description":"Same speed for everyone: On: every character talks at the speech speed, ignoring their own speed settings. Off: characters with their own speed keep it. Default: false.","type":"boolean"},"visualMode":{"description":"Visual style: What plays behind the characters. Motion graphics are designed for each scene and cost extra, by length.\nChoices:\n- gameplay — Gameplay: Classic: game footage behind your character.\n- motion-top — Motion graphics, top: Animated slides in the top panel, gameplay behind. (Adds 550 (30 seconds), 850 (1 minute), 1100 (1.5 minutes), 1400 (2 minutes), 2000 (3 minutes), 3600 (5 minutes) credits; plans: paid)\n- motion-full — Motion graphics, full screen: Full-screen animated slides, no gameplay. (Adds 550 (30 seconds), 850 (1 minute), 1100 (1.5 minutes), 1400 (2 minutes), 2000 (3 minutes), 3600 (5 minutes) credits; plans: paid)\nDefault: gameplay.","type":"string","enum":["gameplay","motion-top","motion-full"]},"motionTheme":{"description":"Slide theme: The colours of the motion graphics slides. Motion graphics only.\nChoices:\n- auto — Auto: The art director picks the slide colours for the topic.\n- dark — Dark: Light words on dark slides.\n- cream — Cream: Dark words on warm cream slides. What a new project starts on.\nDefault: cream.","type":"string","enum":["auto","dark","cream"]},"motionCaptionStyle":{"description":"Motion caption style: How the words are printed on a motion graphics video. Motion graphics only.\nChoices:\n- classic — Classic: Big stroked words. The default.\n- boxed — Boxed: A white card with two-tone read-along words, like the clean explainer reels.\nDefault: classic.","type":"string","enum":["classic","boxed"]},"motionAuthorModel":{"description":"Slide designer: Which AI writes the motion graphics scenes. Its price is the motion graphics surcharge. Motion graphics only.\nChoices:\n- standard — Gemini 3.8 Flash: Fastest to build and the lowest cost per scene. (Adds 550 (30 seconds), 850 (1 minute), 1100 (1.5 minutes), 1400 (2 minutes), 2000 (3 minutes), 3600 (5 minutes) credits)\nDefault: standard.","type":"string","enum":["standard"]},"intelligentVisualSourcing":{"description":"Real pictures in the slides: Let the slide designer add real or generated pictures where a picture explains better than line art. Not charged when the video is made from the wizard or this API. Motion graphics only. Default: true.","type":"boolean"},"motionAssetModel":{"description":"Slide picture maker: Which model makes the pictures for the slides. Not charged when the video is made from the wizard or this API. Motion graphics only.\nChoices:\n- nanoBanana2 — Nano Banana 2: Best overall quality for polished, topic-specific visuals.\n- grokImagine — Grok Imagine: Bold, imaginative compositions for story-led explainers.\n- fluxSchnell — Flux 2 Turbo: Quick generation for simple supporting visuals.\n- fluxDev — Flux Dev: A balance of detail, speed, and prompt accuracy.\n- fluxPro — Flux Pro: Detailed output for complex explanatory visuals.\nDefault: grokImagine.","type":"string","enum":["nanoBanana2","grokImagine","fluxSchnell","fluxDev","fluxPro"]},"motionAssetTier":{"description":"How many slide pictures: The most real or generated pictures the slides may use. Motion graphics only.\nChoices:\n- none — None: Hand-drawn graphics only.\n- balanced — Balanced: Up to 3 sourced images where a picture explains better than line art.\n- rich — Rich: Up to 6 sourced images. Best for longer videos with more to show.\nDefault: balanced.","type":"string","enum":["none","balanced","rich"]},"motionSoundDesign":{"description":"Motion sound design: How loud the beat-timed sound design is. Motion graphics only.\nChoices:\n- subtle — Subtle: Soft ticks and whooshes under the voice, plus a quiet music bed.\n- punchy — Punchy: Louder hits on every beat and cut for high-energy topics.\n- off — Off: Narration and your chosen music only.\nDefault: subtle.","type":"string","enum":["subtle","punchy","off"]},"motionMusicMode":{"description":"Motion music: Where the music of a motion graphics video comes from. Motion graphics only.\nChoices:\n- auto — Auto: We score it for you.\n- track — My track: A track you pick (see music).\n- off — Off: No music at all.\nDefault: auto.","type":"string","enum":["auto","track","off"]},"motionSfxMode":{"description":"Motion sound effects: Where the sound effects of a motion graphics video come from. Motion graphics only.\nChoices:\n- auto — Auto: Timed to the motion and every cut.\n- library — From library: One effect per scene from the library, picked in the app (through the API, scene sound effects are set on gameplay videos only).\n- off — Off: No sound effects.\nDefault: auto.","type":"string","enum":["auto","library","off"]},"background":{"title":"Gameplay background (Character Explainer option background)","description":"Gameplay background: The game footage behind the characters: a game (one of its clips at least as long as the video is picked), \"random\" for any game, or one exact clip at least as long as the video. A preset clip does not repeat, so a game whose clips are all shorter than the video, or a shorter clip, is refused. Leave it out for a Minecraft clip that fits. To use your own clip, send gameplayMediaId instead.\nOne of 106 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=ce&option=background) to see them all.\nChoices:\n- random — Any game: A clip from any game, at least as long as the video.\n- minecraft — Minecraft: A Minecraft clip at least as long as the video. Its clips run up to 5 minutes, so it fits a video up to that long.\n- roblox — Roblox: A Roblox clip at least as long as the video. Its clips run up to 3 minutes, so it fits a video up to that long.\n- gta — GTA: A GTA clip at least as long as the video. Its clips run up to 3 minutes, so it fits a video up to that long.\n- subway — Subway Surfers: A Subway Surfers clip at least as long as the video. Its clips run up to 3 minutes, so it fits a video up to that long.\n- asmr — Satisfying: A Satisfying clip at least as long as the video. Its clips run up to 3 minutes, so it fits a video up to that long.\n- minecraft_part_0 — Minecraft 1 (1:30): Minecraft gameplay, 90 seconds long.\n- minecraft_part_1 — Minecraft 2 (1:15): Minecraft gameplay, 75 seconds long.\n- minecraft_part_2 — Minecraft 3 (1:45): Minecraft gameplay, 105 seconds long.\n- minecraft_part_3 — Minecraft 4 (1:00): Minecraft gameplay, 60 seconds long.\n- minecraft_part_4 — Minecraft 5 (2:00): Minecraft gameplay, 120 seconds long.\n- minecraft_part_5 — Minecraft 6 (1:30): Minecraft gameplay, 90 seconds long.\n- minecraft_part_6 — Minecraft 7 (2:00): Minecraft gameplay, 120 seconds long.\n- minecraft_new_1 — Parkour 1 (2:00): Minecraft gameplay, 120 seconds long.\n- minecraft_new_2 — Parkour 2 (1:30): Minecraft gameplay, 90 seconds long.\n- minecraft_new_3 — Parkour 3 (2:00): Minecraft gameplay, 120 seconds long.\n- minecraft_new_4 — Parkour 4 (1:30): Minecraft gameplay, 90 seconds long.\n- minecraft_new_5 — Parkour 5 (2:30): Minecraft gameplay, 150 seconds long.\n- minecraft_new_6 — Parkour 6 (2:00): Minecraft gameplay, 120 seconds long.\n- minecraft_new_7 — Parkour 7 (1:30): Minecraft gameplay, 90 seconds long.\n- minecraft_new_8 — Parkour 8 (3:05): Minecraft gameplay, 185 seconds long.\n- parkour_v2_1_01_90s — V2 1-1 (1:30): Minecraft gameplay, 90 seconds long.\n- parkour_v2_1_02_180s — V2 1-2 (3:00): Minecraft gameplay, 180 seconds long.\n- parkour_v2_1_03_300s — V2 1-3 (5:00): Minecraft gameplay, 300 seconds long.\n- parkour_v2_1_04_90s — V2 1-4 (1:30): Minecraft gameplay, 90 seconds long.\n- parkour_v2_1_05_180s — V2 1-5 (3:00): Minecraft gameplay, 180 seconds long.\n- parkour_v2_1_06_114s — V2 1-6 (1:54): Minecraft gameplay, 114 seconds long.\n- parkour_v2_2_01_90s — V2 2-1 (1:30): Minecraft gameplay, 90 seconds long.\n- parkour_v2_2_02_180s — V2 2-2 (3:00): Minecraft gameplay, 180 seconds long.\n- parkour_v2_3_01_90s — V2 3-1 (1:30): Minecraft gameplay, 90 seconds long.\n…and 76 more.\nDefault: A Minecraft clip long enough for the video (leave it out).","type":"string"},"gameplayMediaId":{"description":"One of your videos (MP4, WebM or MOV) from your media library (autoclips_media), played behind the characters instead of a preset clip. A media id: 24 letters and digits. Default: A preset clip (see background) (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"gameplaySpeed":{"description":"Gameplay speed: How fast the background footage plays.\nChoices:\n- 0.5 — 0.5x: Slow motion.\n- 0.75 — 0.75x: Slower.\n- 1 — 1x: Normal speed.\n- 1.25 — 1.25x: Faster.\n- 1.5 — 1.5x: Fast.\n- 2 — 2x: Double speed.\nDefault: 1.\nSend the value as text (\"1.25\") or a number (1.25).","anyOf":[{"description":"Gameplay speed: How fast the background footage plays.\nChoices:\n- 0.5 — 0.5x: Slow motion.\n- 0.75 — 0.75x: Slower.\n- 1 — 1x: Normal speed.\n- 1.25 — 1.25x: Faster.\n- 1.5 — 1.5x: Fast.\n- 2 — 2x: Double speed.\nDefault: 1.","type":"string","enum":["1","2","0.5","0.75","1.25","1.5"]},{"type":"number","enum":[0.5,0.75,1,1.25,1.5,2]}]},"music":{"title":"Background music (Character Explainer option music)","description":"Background music: The music under the voices: none, one of the app's soundtracks, or a mood (a track of that mood is picked for you, as automations do). The copyright-free AutoClips library tracks are in musicLibraryTrack; send one or the other. Free.\nOne of 240 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=ce&option=music) to see them all.\nChoices:\n- none — No music: Voices only.\n- mood:popular — Popular (picked for you): Fan-favorite tracks — deep, dramatic, and atmospheric vibes. A track of this mood is picked for the video.\n- mood:playful — Playful & Fun (picked for you): Light, quirky, comedic — perfect for funny educational content. A track of this mood is picked for the video.\n- mood:sneaky — Sneaky & Curious (picked for you): Tip-toeing, mischievous, investigative vibes. A track of this mood is picked for the video.\n- mood:mysterious — Mysterious & Dark (picked for you): Eerie, suspenseful, atmospheric tension. A track of this mood is picked for the video.\n- mood:epic — Epic & Dramatic (picked for you): Cinematic, powerful, building intensity. A track of this mood is picked for the video.\n- mood:chill — Chill & Calm (picked for you): Relaxed, dreamy, gentle background. A track of this mood is picked for the video.\n- mood:upbeat — Upbeat & Energetic (picked for you): Bouncy, lively, feel-good energy. A track of this mood is picked for the video.\n- mood:whimsical — Whimsical & Weird (picked for you): Absurd, circus-like, chaotic fun. A track of this mood is picked for the video.\n- mood:v3-animals — Animals & Wildlife, copyright-free (picked for you): Nature documentaries, wildlife. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-crime — Crime & Mystery, copyright-free (picked for you): Dark, suspenseful, investigative. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-general — General, copyright-free (picked for you): Versatile tracks for any topic. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-history — History, copyright-free (picked for you): Historical, documentary, period. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-horror — Horror, copyright-free (picked for you): Dark, terrifying, dread. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-science — Science, copyright-free (picked for you): Documentary, educational, wonder. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-space — Space & Cosmos, copyright-free (picked for you): Ethereal, cosmic, vast. A copyright-free AutoClips library track of this kind is picked for the video.\n- hide-and-sneak — Hide and Sneak: The Fly Guy Five. Popular soundtrack.\n- old-time-circus — Old Time Circus: Luella Gren. Popular soundtrack.\n- lurking-behind — Lurking Behind: The Fly Guy Five. Popular soundtrack.\n- ce-burning-memory — It's Just a Burning Memory: The Caretaker. Popular soundtrack.\n- ce-f-down — F.Down: Unknown. Popular soundtrack.\n- ce-school-rooftop — School Rooftop (Bird Sounds): hisohkah & WMD. Popular soundtrack.\n- ce-promise-reprise — Promise (Reprise): Unknown. Popular soundtrack.\n- ce-everything-in-its-right-place — Everything In Its Right Place (Instrumental): Radiohead. Popular soundtrack.\n- ce-six-forty-seven — Six Forty Seven: Instupendo. Popular soundtrack.\n- ce-numbers — Numbers (Instrumental): TEMPOREX. Popular soundtrack.\n- ce-fallen-down — Fallen Down (Panic Room): Undertale. Popular soundtrack.\n- ce-char-remix — Char (Remix) Slowed: Crystal Castles. Popular soundtrack.\n- ce-empathy — Empathy (Slowed + Reverb): Crystal Castles. Popular soundtrack.\n- ce-aleph — ALEPH (Slowed + Reverb): Gesaffelstein. Popular soundtrack.\n…and 210 more.\nDefault: none.","type":"string"},"musicLibraryTrack":{"title":"AutoClips library track (Character Explainer option musicLibraryTrack)","description":"AutoClips library track: One track of the copyright-free AutoClips music library, as the wizard's Music step lists it. Send it instead of music. Free.\nOne of 307 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=ce&option=musicLibraryTrack) to see them all.\nChoices:\n- v3-animals-wildlife-01-wild-kingdom-v1 — Wild Kingdom: Animals track: Upbeat, Nature, Documentary (2:16).\n- v3-animals-wildlife-01-wild-kingdom-v2 — Wild Kingdom: Animals track: Upbeat, Nature, Documentary (1:45).\n- v3-animals-wildlife-02-migration-path-v1 — Migration Path: Animals track: Sweeping, Cinematic, Emotional (2:53).\n- v3-animals-wildlife-02-migration-path-v2 — Migration Path: Animals track: Sweeping, Cinematic, Emotional (2:53).\n- v3-animals-wildlife-03-jungle-pulse-v1 — Jungle Pulse: Animals track: Rhythmic, Percussive, Tropical (1:22).\n- v3-animals-wildlife-03-jungle-pulse-v2 — Jungle Pulse: Animals track: Rhythmic, Percussive, Tropical (2:12).\n- v3-animals-wildlife-04-ocean-giants-v1 — Ocean Giants: Animals track: Majestic, Orchestral, Oceanic (3:55).\n- v3-animals-wildlife-04-ocean-giants-v2 — Ocean Giants: Animals track: Majestic, Orchestral, Oceanic (2:58).\n- v3-animals-wildlife-05-wings-of-freedom — Wings of Freedom: Animals track: Soaring, Cinematic, Uplifting (2:40).\n- v3-animals-wildlife-05-wings-of-freedom-v1 — Wings of Freedom: Animals track: Soaring, Cinematic, Uplifting (2:40).\n- v3-animals-wildlife-05-wings-of-freedom-v2 — Wings of Freedom: Animals track: Soaring, Cinematic, Uplifting (3:03).\n- v3-animals-01-predator-instinct — Predator Instinct: Animals track: Intense, Percussion, Primal (1:38).\n- v3-animals-02-coral-reef-dance — Coral Reef Dance: Animals track: Playful, Tropical, Underwater (2:05).\n- v3-animals-03-savanna-sunrise — Savanna Sunrise: Animals track: Warm, Acoustic, African (3:41).\n- v3-animals-04-arctic-whispers — Arctic Whispers: Animals track: Gentle, Ambient, Icy (2:54).\n- v3-animals-05-night-creatures — Night Creatures: Animals track: Mysterious, Nocturnal, Ambient (4:03).\n- v3-crime-mystery-01-cold-case-files-v1 — Cold Case Files: Crime track: Noir, Jazz, Detective (4:06).\n- v3-crime-mystery-01-cold-case-files-v2 — Cold Case Files: Crime track: Noir, Jazz, Detective (3:48).\n- v3-crime-mystery-02-under-surveillance-v1 — Under Surveillance: Crime track: Electronic, Thriller, Pulsing (5:08).\n- v3-crime-mystery-02-under-surveillance-v2 — Under Surveillance: Crime track: Electronic, Thriller, Pulsing (3:18).\n- v3-crime-mystery-03-the-investigation-v1 — The Investigation: Crime track: Dark, Detective, Piano (2:30).\n- v3-crime-mystery-03-the-investigation-v2 — The Investigation: Crime track: Dark, Detective, Piano (3:19).\n- v3-crime-mystery-04-hidden-evidence-v1 — Hidden Evidence: Crime track: Suspenseful, Ambient, Urgent (2:02).\n- v3-crime-mystery-04-hidden-evidence-v2 — Hidden Evidence: Crime track: Suspenseful, Ambient, Urgent (3:05).\n- v3-crime-mystery-05-midnight-pursuit-v1 — Midnight Pursuit: Crime track: Intense, Chase, Electronic (3:12).\n- v3-crime-mystery-05-midnight-pursuit-v2 — Midnight Pursuit: Crime track: Intense, Chase, Electronic (3:40).\n- v3-crime-01-blood-trail — Blood Trail: Crime track: Gritty, Electronic, Dark, Bass (3:45).\n- v3-crime-02-alibi-unraveled — Alibi Unraveled: Crime track: Tense, Piano, Thriller (1:55).\n- v3-crime-03-forensic-mind — Forensic Mind: Crime track: Clinical, Synth, Procedural (2:48).\n- v3-crime-04-double-cross — Double Cross: Crime track: Jazzy, Noir, Suspenseful (3:13).\n…and 277 more.\nDefault: No library track (see music) (leave it out).","type":"string"},"musicVolume":{"description":"Music volume: How loud the music is under the voices, from 0 (silent) to 1 (full). From 0 to 1, in steps of 0.01. Default: 0.15.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"showCaptions":{"description":"Captions: Show the spoken words on screen. Default: true.","type":"boolean"},"captionFont":{"description":"Caption font: The font of the captions.\nChoices:\n- BebasNeue — Bebas Neue: Bebas Neue lettering.\n- Anton — Anton: Anton lettering.\n- Montserrat — Montserrat: Montserrat lettering.\n- LeagueSpartan — League Spartan: League Spartan lettering.\nDefault: BebasNeue.","type":"string","enum":["BebasNeue","Anton","Montserrat","LeagueSpartan"]},"captionSizeMultiplier":{"description":"Caption size: How big the captions are: 1 is normal. From 0.7 to 1.5, in steps of 0.05. Default: 1.","type":"number","minimum":0.7,"maximum":1.5,"multipleOf":0.05},"captionVerticalPosition":{"description":"Caption height: Where the captions sit, in percent of the frame from the top. From 5 to 85 percent. Default: 44.","type":"integer","minimum":5,"maximum":85},"captionColor":{"description":"Caption colour: The colour of the words not being spoken, as #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"captionHighlightColor":{"description":"Caption highlight colour: The colour of the word being spoken, as #RRGGBB. Default: #FFD700.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"captionStrokeColor":{"description":"Caption outline colour: The colour of the outline around the words, as #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkType":{"description":"Watermark: A mark on the finished video: your text or your picture. Free videos also carry a small \"Made with Autoclips.app\" badge, whatever you pick here; a paid plan removes it.\nChoices:\n- none — None: No watermark of your own (a free video still carries the \"Made with Autoclips.app\" badge).\n- text — Text: Your handle or brand name as text (watermarkText).\n- image — Picture: Your logo from your media library (watermarkMediaId).\nDefault: none.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"Watermark text: The text of a text watermark. Default: No text (leave it out).","type":"string","minLength":1,"maxLength":50},"watermarkTextColor":{"description":"Watermark text colour: The colour of a text watermark, as #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundColor":{"description":"Watermark background colour: The colour of the box behind a text watermark, as #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundOpacity":{"description":"Watermark background opacity: How solid the box behind a text watermark is, from 0 (none) to 1 (solid). From 0 to 1, in steps of 0.01. Default: 0.5.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"watermarkMediaId":{"description":"For a picture watermark: one of your pictures from your media library (autoclips_media). A media id: 24 letters and digits. Default: No picture (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"watermarkImageOpacity":{"description":"Watermark picture opacity: How solid a picture watermark is, from 0.3 to 1 (solid). From 0.3 to 1, in steps of 0.01. Default: 0.7.","type":"number","minimum":0.3,"maximum":1,"multipleOf":0.01},"watermarkVerticalPosition":{"description":"Watermark height: Where the watermark sits, in percent of the frame from the top. From 10 to 90 percent. Default: 85.","type":"integer","minimum":10,"maximum":90},"watermarkHorizontalPosition":{"description":"Watermark across: Where the watermark sits, in percent of the frame from the left. From 5 to 95 percent. Default: 85.","type":"integer","minimum":5,"maximum":95},"watermarkScale":{"description":"Watermark size: How big the watermark is: 1 is normal, from 0.5 to 3. From 0.5 to 3, in steps of 0.01. Default: 1.","type":"number","minimum":0.5,"maximum":3,"multipleOf":0.01},"outroId":{"description":"Outro: An end card from your outros (autoclips_outros) added after the last scene. Paid plans only: on a free plan it is refused with plan_required. Send \"none\" for no outro: on a new project that is the same as leaving it out, and an update takes the saved outro off. Default: No outro (leave it out).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"characters":{"description":"One character talks alone; 2 to 6 talk to each other. A longer video holds more: up to 3 for 30 seconds, 4 for 1 minute, 5 for 1.5 minutes and 6 for 2 minutes or more (a length between two of these counts as the longer one). Pick each character by its slug from ce_characters list: built-in ones and your own.","minItems":1,"maxItems":6,"type":"array","items":{"type":"object","properties":{"character":{"description":"The character's slug from ce_characters list (or its exact name).","type":"string","minLength":1,"maxLength":120},"position":{"description":"Character position: Which corner a character stands in.\nChoices:\n- bottom-left — Bottom left: The character stands in the bottom left corner.\n- bottom-right — Bottom right: The character stands in the bottom right corner.\nDefault: Alternates, the first on the left (leave it out).","type":"string","enum":["bottom-left","bottom-right"]},"personality":{"description":"Character personality: The role a character plays in the conversation. Only one character is the lead (\"authority\"). When several would be, the first one you sent as \"authority\" keeps the role (if you sent none, the first one that is the lead by default), and the others become Skeptical Normies.\nChoices:\n- authority — Authority: The main character who sees the full picture, resolves tension.\n- naive-beginner — Naive Beginner: Asks basic questions everyone is thinking.\n- chaotic-zoomer — Chaotic Zoomer: Meme energy, half-informed but entertaining.\n- skeptical-normie — Skeptical Normie: Questions everything, healthy skepticism.\n- insider — Insider: Acts knowledgeable, implies hidden knowledge.\n- provocateur — Provocateur: Stirs controversy, pushes boundaries.\n- storyteller — Storyteller: Adds anecdotes, real-world examples.\n- comedian — Comedian: Turns everything into jokes, lightens mood.\n- philosopher — Philosopher: Goes deep, asks \"why\" behind everything.\n- hype-man — Hype Man: Gets excited, amplifies energy.\nDefault: The character's own default, else the lead (leave it out).","type":"string","enum":["authority","naive-beginner","chaotic-zoomer","skeptical-normie","insider","provocateur","storyteller","comedian","philosopher","hype-man"]}},"required":["character"],"additionalProperties":false}}},"required":["characters"],"additionalProperties":false},"example":{"topic":"How do black holes form?","characters":[{"character":"peter-griffin"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"ce"},"title":{"type":"string"},"status":{"description":"Where the project is: draft, writing_script, script_ready, needs_speakers, waiting_for_approval, making, prepared_in_app, finished, no_video, failed, stalled.","type":"string","enum":["draft","writing_script","script_ready","needs_speakers","waiting_for_approval","making","prepared_in_app","finished","no_video","failed","stalled"]},"statusText":{"description":"The status in plain words.","type":"string"},"step":{"description":"What is being made right now, while status is making.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"type":"number"},"revision":{"description":"Send it back as expectedRevision when you change scenes.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"appLink":{"description":"Where to open the project in the app.","type":"string"},"autoPost":{"description":"Where a finished render posts itself.","type":"object","properties":{"platforms":{"type":"array","items":{"type":"string"}}},"required":["platforms"],"additionalProperties":{}},"nextStep":{"description":"What to do next, in plain words.","type":"string"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"settings":{"description":"The project's settings, in the same words create and update take.","type":"object","properties":{},"additionalProperties":{}},"characters":{"description":"The cast, lead first.","type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"position":{"description":"Which corner the character stands in.","type":"string"},"personality":{"description":"The role the character plays in the conversation.","anyOf":[{"type":"string"},{"type":"null"}]},"builtIn":{"type":"boolean"},"pictureUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slug","name","position","personality","builtIn","pictureUrl"],"additionalProperties":false}},"price":{"anyOf":[{"type":"object","properties":{"credits":{"description":"What rendering this video costs right now, in credits (nothing is charged until you render it with ce_render start).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"alreadyReserved":{"description":"Credits already set aside for this video (when it was prepared in the app, or by an earlier render of it that did not finish): only the difference is charged.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"balance":{"description":"Your credit balance now.","anyOf":[{"type":"number"},{"type":"null"}]},"notes":{"description":"How the price was worked out, in plain words.","type":"array","items":{"type":"string"}}},"required":["credits","alreadyReserved","balance","notes"],"additionalProperties":false},{"type":"null"}]}},"required":["id","product","title","status","statusText","step","progress","revision","appLink","autoPost","nextStep","createdAt","updatedAt","settings","characters","price"],"additionalProperties":{}},"notes":{"description":"What was changed from what you sent, and anything to know before the next step, in plain words.","type":"array","items":{"type":"string"}}},"required":["project","notes"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","product":"ce","title":"How do black holes form?","status":"draft","statusText":"Draft. Next: write the script.","step":null,"progress":0,"revision":1791795600120,"appLink":"https://app.autoclips.app/character-explainer?sessionId=3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","autoPost":{"platforms":[]},"nextStep":"Write the script: ce_script generate.","createdAt":"2026-10-12T09:00:00.000Z","updatedAt":"2026-10-12T09:00:00.120Z","settings":{"inputMode":"topic","topic":"How do black holes form?","hasCustomScript":false,"style":"explainer","durationSeconds":30,"language":"en","scriptMode":"normal","customInstructions":null,"ttsModel":"eleven_v4","voiceEmotion":"off","speechSpeed":1.15,"overrideSpeechSpeed":false,"visualMode":"gameplay","motionTheme":"cream","motionCaptionStyle":"classic","motionAuthorModel":"standard","intelligentVisualSourcing":true,"motionAssetModel":"grokImagine","motionAssetTier":"balanced","motionSoundDesign":"subtle","motionMusicMode":"auto","motionSfxMode":"auto","background":"minecraft_part_0","gameplayMediaId":null,"ownGameplay":false,"gameplaySpeed":"1","music":"none","musicLibraryTrack":null,"musicVolume":0.15,"showCaptions":true,"captionFont":"BebasNeue","captionSizeMultiplier":1,"captionVerticalPosition":44,"captionColor":"#FFFFFF","captionHighlightColor":"#FFD700","captionStrokeColor":"#000000","characterSizeMultiplier":1,"characterFloating":false,"floatingIntensity":50,"characterPlacementX":null,"characterPlacementY":null,"watermarkType":"none","watermarkText":null,"outroId":null},"characters":[{"slug":"peter-griffin","name":"Peter Griffin","position":"bottom-left","personality":"authority","builtIn":true,"pictureUrl":"https://media.autoclips.app/character-references/base-characters/peter-griffin.webp"}],"price":{"credits":50,"alreadyReserved":0,"balance":1200,"notes":[]}},"notes":[]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"ce_projects_list","summary":"Your Character Explainer projects, most recently changed first, with their status, thumbnail and video link.","description":"Lists your Character Explainer projects the way the app's project picker does: most recently changed first, deleted ones and drafts made by Ask AutoClips that you never opened left out. Each item says where the project is, as ce_projects get does, with its visual style, a thumbnail and the video link once it is finished. Page with limit and next_cursor.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"ce.projects.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_projects action=list","parameters":[{"name":"limit","in":"query","required":false,"schema":{"description":"How many projects to return (1 to 50, default 20). Example: 10.","type":"integer","minimum":1,"maximum":50},"description":"How many projects to return (1 to 50, default 20). Example: 10.","example":2},{"name":"cursor","in":"query","required":false,"schema":{"description":"The next_cursor from the previous page. Leave it out for the first page.","type":"string","maxLength":512},"description":"The next_cursor from the previous page. Leave it out for the first page.","example":"ZGxwMToy"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"ce"},"title":{"type":"string"},"status":{"description":"Where the project is: draft, writing_script, script_ready, needs_speakers, waiting_for_approval, making, prepared_in_app, finished, no_video, failed, stalled.","type":"string","enum":["draft","writing_script","script_ready","needs_speakers","waiting_for_approval","making","prepared_in_app","finished","no_video","failed","stalled"]},"statusText":{"description":"The status in plain words.","type":"string"},"step":{"description":"What is being made right now, while status is making.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"type":"number"},"revision":{"description":"Send it back as expectedRevision when you change scenes.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"appLink":{"description":"Where to open the project in the app.","type":"string"},"autoPost":{"description":"Where a finished render posts itself.","type":"object","properties":{"platforms":{"type":"array","items":{"type":"string"}}},"required":["platforms"],"additionalProperties":{}},"nextStep":{"description":"What to do next, in plain words.","type":"string"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"visualMode":{"description":"What plays behind the characters: gameplay, motion-top (motion graphics on top) or motion-full (full-screen motion graphics).","type":"string","enum":["gameplay","motion-top","motion-full"]},"visualModeText":{"description":"The visual style in the app's words.","type":"string"},"thumbnail":{"description":"A picture for the project: a frame of the video once there is one, else the character.","anyOf":[{"type":"string"},{"type":"null"}]},"thumbnailIsPlaceholder":{"description":"true when thumbnail is the character, not a frame of the video.","type":"boolean"}},"required":["id","product","title","status","statusText","step","progress","revision","appLink","autoPost","nextStep","createdAt","updatedAt","visualMode","visualModeText","thumbnail","thumbnailIsPlaceholder"],"additionalProperties":{}}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"has_more":{"type":"boolean"}},"required":["items","next_cursor","has_more"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"items":[{"id":"b8e05f3c-2a71-4c9d-8e46-1f3a7d5c9b20","product":"ce","title":"How black holes are born","status":"finished","statusText":"Finished.","step":null,"progress":100,"revision":1791727560000,"appLink":"https://app.autoclips.app/character-explainer?sessionId=b8e05f3c-2a71-4c9d-8e46-1f3a7d5c9b20","autoPost":{"platforms":[]},"nextStep":"Watch it, post it (autoclips_publish) or read its versions (ce_render versions).","createdAt":"2026-10-11T14:00:00.000Z","updatedAt":"2026-10-11T14:06:00.000Z","video":{"url":"https://media.autoclips.app/videos/character-explainer/b8e05f3c-2a71-4c9d-8e46-1f3a7d5c9b20.mp4","thumbnail":"https://media.autoclips.app/thumbnails/character-explainer/b8e05f3c-2a71-4c9d-8e46-1f3a7d5c9b20.jpg","finishedAt":"2026-10-11T14:05:00.000Z"},"editedFrom":"7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13","visualMode":"gameplay","visualModeText":"Gameplay","thumbnail":"https://media.autoclips.app/thumbnails/character-explainer/b8e05f3c-2a71-4c9d-8e46-1f3a7d5c9b20.jpg","thumbnailIsPlaceholder":false},{"id":"7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13","product":"ce","title":"How black holes are born","status":"finished","statusText":"Finished.","step":null,"progress":100,"revision":1791620460000,"appLink":"https://app.autoclips.app/character-explainer?sessionId=7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13","autoPost":{"platforms":[]},"nextStep":"Watch it, post it (autoclips_publish) or read its versions (ce_render versions).","createdAt":"2026-10-10T08:00:00.000Z","updatedAt":"2026-10-10T08:21:00.000Z","video":{"url":"https://media.autoclips.app/videos/character-explainer/7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13.mp4","thumbnail":"https://media.autoclips.app/thumbnails/character-explainer/7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13.jpg","finishedAt":"2026-10-10T08:20:00.000Z"},"editedFrom":null,"visualMode":"gameplay","visualModeText":"Gameplay","thumbnail":"https://media.autoclips.app/thumbnails/character-explainer/7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13.jpg","thumbnailIsPlaceholder":false}],"next_cursor":"ZGxwMToy","has_more":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/projects/quick":{"post":{"operationId":"ce_projects_quick_create","summary":"Make a whole Character Explainer video in one go: script, voices and render, plus pictures and sound effects if you ask. Answers with a job.","description":"Quick Create writes the script, makes the scene pictures you ask for, picks sound effects if you want them, records the voices and renders the video, and you follow a job (autoclips_jobs) until it is ready. It takes most of the choices ce_projects create takes for a gameplay video: a topic (a web link in it is read while the script is written; a link to a private or internal address is refused) or your own script, the style, length, language, script quality, extra instructions, the characters (ce_characters list shows them) with their corner and role, the speech speed and voice emotion, the gameplay background or one of your own videos, music, captions and a watermark. It does not take the voice model, the character placement or an outro. On top of that: sceneImages (a picture model, or real photos from the web) and its style, soundEffects, and reviewScript, which stops after the script and waits for your OK (ce_script review) before anything is charged. What you approve is a spending limit, charged step by step as it runs: the scene pictures are charged together when the picture step starts (a picture that fails is given back), then the video when its turn comes, so the run usually spends less. If the video fails after it started, its credits are given back, but the pictures already made stay on the project and stay charged (ce_render start can make the video from them). The limit is the most the run can be charged: the video price at its length (a pasted script longer than the length is billed at its own length) plus the picture price for the most pictures the length gets. Over REST, max_credits must cover the limit; your balance must cover it too when it starts. Free plans make 30-second videos, paid for from the 150 credits a new account gets, and every free video carries a small \"Made with Autoclips.app\" badge. A longer length is set to 30 seconds, and the note says so with the way to a longer video; your own script, the Trending, Quality and Ultra scripts, scene pictures and motion graphics need a paid plan. Quick Create makes gameplay videos only: for motion graphics, make it step by step: ce_projects create with visualMode motion-top or motion-full, then ce_script generate, then ce_render start. Sending the same request again with the same Idempotency-Key hands back the same project and job; it never starts a second one. If a try failed after its video had started, the same request sent again within 10 minutes (even with a new key or a new approval) carries on that video instead of starting a second one, and says so (continued: true).\n\n**Permissions:** spend.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. The limit is the most Character Explainer Quick Create can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Character Explainer"],"security":[{"bearerAuth":["spend"]}],"x-autoclips-operation":"ce.projects.quick_create","x-autoclips-scopes":["spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"ce_projects action=quick_create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputMode":{"description":"What the script comes from: Write the script from a topic, or use a script you paste.\nChoices:\n- topic — Topic: The AI writes the script from your topic.\n- custom_script — Your script: Your own script, split into scenes and voiced as written. (Billed at the longer of the length you pick and how long your script takes to say (about 500 characters per 30 seconds; speaker names are not counted); plans: paid)\nDefault: topic.","type":"string","enum":["topic","custom_script"]},"topic":{"description":"Topic: What the video is about, in your words (research notes and links are fine). A web link in it is read from the web while the script is written; a link to a private or internal address is refused. No default: ask the user.","type":"string","minLength":1,"maxLength":5000},"customScript":{"description":"Your script: The script to use, for \"Your script\" (inputMode custom_script). It sets the billed length: about 500 spoken characters per 30 seconds, never less than the length you pick. Speaker names (\"Peter:\"), markdown and blank lines are not counted; Japanese, Chinese, Thai and Korean count at their own speaking pace, and a script that takes longer than 5 minutes to say is refused. Default: No pasted script (leave it out).","type":"string","minLength":20,"maxLength":5000},"style":{"description":"Style: How the script is written.\nChoices:\n- explainer — Explainer: Show how something really works.\n- controversy — Controversy: Lay out a case, exhibit by exhibit.\n- educational — Educational: Teach something new.\n- funny — Comedy: Make them laugh.\n- storytelling — Story: Tell a story.\n- brainrot — Brain Rot: Gen Z chaos mode: fast, loud and full of slang.\nDefault: explainer.","type":"string","enum":["explainer","controversy","educational","funny","storytelling","brainrot"]},"durationSeconds":{"description":"How long the video is meant to be. It is billed at the price band it rounds up to (30, 60, 90, 120, 180 or 300 seconds): a 40-second video costs what a 1-minute one does. Free plans make 30-second videos: a longer length is set to 30 seconds, with a note. Send it as a number (60); its id as text (\"60\") is taken too. One of 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 180, 240, 300 seconds. Default: 30.","anyOf":[{"type":"number","enum":[30,40,50,60,70,80,90,100,110,120,180,240,300]},{"type":"string","pattern":"^(?:30|40|50|60|70|80|90|100|110|120|180|240|300)$"}]},"language":{"title":"Language (Character Explainer option language)","description":"Language: The language of the script, the voices and the captions. Every character in the video must be able to speak it (ce_characters list shows which can).\nOne of 94 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=ce&option=language) to see them all.\nChoices:\n- en — English: English script, voices and captions.\n- es — Spanish: Spanish script, voices and captions.\n- pt — Portuguese: Portuguese script, voices and captions.\n- fr — French: French script, voices and captions.\n- de — German: German script, voices and captions.\n- hi — Hindi: Hindi script, voices and captions.\n- ar — Arabic: Arabic script, voices and captions.\n- ja — Japanese: Japanese script, voices and captions.\n- zh — Chinese: Chinese script, voices and captions.\n- id — Indonesian: Indonesian script, voices and captions.\n- ru — Russian: Russian script, voices and captions.\n- tr — Turkish: Turkish script, voices and captions.\n- ko — Korean: Korean script, voices and captions.\n- it — Italian: Italian script, voices and captions.\n- nl — Dutch: Dutch script, voices and captions.\n- pl — Polish: Polish script, voices and captions.\n- ro — Romanian: Romanian script, voices and captions.\n- cs — Czech: Czech script, voices and captions.\n- sk — Slovak: Slovak script, voices and captions.\n- hu — Hungarian: Hungarian script, voices and captions.\n- sv — Swedish: Swedish script, voices and captions.\n- da — Danish: Danish script, voices and captions.\n- no — Norwegian: Norwegian script, voices and captions.\n- fi — Finnish: Finnish script, voices and captions.\n- is — Icelandic: Icelandic script, voices and captions.\n- et — Estonian: Estonian script, voices and captions.\n- lv — Latvian: Latvian script, voices and captions.\n- lt — Lithuanian: Lithuanian script, voices and captions.\n- el — Greek: Greek script, voices and captions.\n- bg — Bulgarian: Bulgarian script, voices and captions.\n…and 64 more.\nDefault: en.","type":"string"},"scriptMode":{"description":"Script quality: Which writer makes the script. It sets the video price, by length.\nChoices:\n- normal — Normal: Quick, solid scripts for subjects that do not change: how-tos, explainers, timeless facts. (50 (30 seconds), 50 (1 minute), 100 (1.5 minutes), 200 (2 minutes), 300 (3 minutes), 500 (5 minutes) credits)\n- max — Trending: Looks the topic up on the web as it writes, so it can use real facts from this week. For news, launches and anything happening right now. (100 (30 seconds), 100 (1 minute), 200 (1.5 minutes), 300 (2 minutes), 450 (3 minutes), 750 (5 minutes) credits; plans: paid)\n- pro — Quality: The most polished writing: stronger hooks, better pacing, endings that land. No web search. (100 (30 seconds), 100 (1 minute), 200 (1.5 minutes), 300 (2 minutes), 450 (3 minutes), 750 (5 minutes) credits; plans: paid)\n- ultra — Ultra: The strongest writing plus live web research: the best script we can make, whatever the topic. (200 (30 seconds), 200 (1 minute), 300 (1.5 minutes), 400 (2 minutes), 600 (3 minutes), 1000 (5 minutes) credits; plans: paid)\nDefault: normal.","type":"string","enum":["normal","max","pro","ultra"]},"customInstructions":{"description":"Extra instructions: Anything the writer should keep in mind (tone, audience, a call to action). The wizard has no box for it; automations and the original AI tool use it. Default: None (leave it out).","type":"string","minLength":1,"maxLength":1000},"speechSpeed":{"description":"Speech speed: How fast the characters talk: 1 is normal, 1.15 is a little quicker for better pacing. From 0.75 to 1.5, in steps of 0.05. Default: 1.15.","type":"number","minimum":0.75,"maximum":1.5,"multipleOf":0.05},"overrideSpeechSpeed":{"description":"Same speed for everyone: On: every character talks at the speech speed, ignoring their own speed settings. Off: characters with their own speed keep it. Default: false.","type":"boolean"},"voiceEmotion":{"description":"Voice emotion: How much emotion the voices carry.\nChoices:\n- off — Off: A neutral, steady tone throughout.\n- subtle — Subtle: Light emotion: hooks sound a little more engaging.\n- normal — Normal: Emotion from the context: hooks are exciting, questions are curious.\n- expressive — Expressive: Strong emotion, for entertainment and comedy.\nDefault: off.","type":"string","enum":["off","subtle","normal","expressive"]},"background":{"title":"Gameplay background (Character Explainer option background)","description":"Gameplay background: The game footage behind the characters: a game (one of its clips at least as long as the video is picked), \"random\" for any game, or one exact clip at least as long as the video. A preset clip does not repeat, so a game whose clips are all shorter than the video, or a shorter clip, is refused. Leave it out for a Minecraft clip that fits. To use your own clip, send gameplayMediaId instead.\nOne of 106 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=ce&option=background) to see them all.\nChoices:\n- random — Any game: A clip from any game, at least as long as the video.\n- minecraft — Minecraft: A Minecraft clip at least as long as the video. Its clips run up to 5 minutes, so it fits a video up to that long.\n- roblox — Roblox: A Roblox clip at least as long as the video. Its clips run up to 3 minutes, so it fits a video up to that long.\n- gta — GTA: A GTA clip at least as long as the video. Its clips run up to 3 minutes, so it fits a video up to that long.\n- subway — Subway Surfers: A Subway Surfers clip at least as long as the video. Its clips run up to 3 minutes, so it fits a video up to that long.\n- asmr — Satisfying: A Satisfying clip at least as long as the video. Its clips run up to 3 minutes, so it fits a video up to that long.\n- minecraft_part_0 — Minecraft 1 (1:30): Minecraft gameplay, 90 seconds long.\n- minecraft_part_1 — Minecraft 2 (1:15): Minecraft gameplay, 75 seconds long.\n- minecraft_part_2 — Minecraft 3 (1:45): Minecraft gameplay, 105 seconds long.\n- minecraft_part_3 — Minecraft 4 (1:00): Minecraft gameplay, 60 seconds long.\n- minecraft_part_4 — Minecraft 5 (2:00): Minecraft gameplay, 120 seconds long.\n- minecraft_part_5 — Minecraft 6 (1:30): Minecraft gameplay, 90 seconds long.\n- minecraft_part_6 — Minecraft 7 (2:00): Minecraft gameplay, 120 seconds long.\n- minecraft_new_1 — Parkour 1 (2:00): Minecraft gameplay, 120 seconds long.\n- minecraft_new_2 — Parkour 2 (1:30): Minecraft gameplay, 90 seconds long.\n- minecraft_new_3 — Parkour 3 (2:00): Minecraft gameplay, 120 seconds long.\n- minecraft_new_4 — Parkour 4 (1:30): Minecraft gameplay, 90 seconds long.\n- minecraft_new_5 — Parkour 5 (2:30): Minecraft gameplay, 150 seconds long.\n- minecraft_new_6 — Parkour 6 (2:00): Minecraft gameplay, 120 seconds long.\n- minecraft_new_7 — Parkour 7 (1:30): Minecraft gameplay, 90 seconds long.\n- minecraft_new_8 — Parkour 8 (3:05): Minecraft gameplay, 185 seconds long.\n- parkour_v2_1_01_90s — V2 1-1 (1:30): Minecraft gameplay, 90 seconds long.\n- parkour_v2_1_02_180s — V2 1-2 (3:00): Minecraft gameplay, 180 seconds long.\n- parkour_v2_1_03_300s — V2 1-3 (5:00): Minecraft gameplay, 300 seconds long.\n- parkour_v2_1_04_90s — V2 1-4 (1:30): Minecraft gameplay, 90 seconds long.\n- parkour_v2_1_05_180s — V2 1-5 (3:00): Minecraft gameplay, 180 seconds long.\n- parkour_v2_1_06_114s — V2 1-6 (1:54): Minecraft gameplay, 114 seconds long.\n- parkour_v2_2_01_90s — V2 2-1 (1:30): Minecraft gameplay, 90 seconds long.\n- parkour_v2_2_02_180s — V2 2-2 (3:00): Minecraft gameplay, 180 seconds long.\n- parkour_v2_3_01_90s — V2 3-1 (1:30): Minecraft gameplay, 90 seconds long.\n…and 76 more.\nDefault: A Minecraft clip long enough for the video (leave it out).","type":"string"},"gameplayMediaId":{"description":"One of your videos (MP4, WebM or MOV) from your media library (autoclips_media), played behind the characters instead of a preset clip. A media id: 24 letters and digits. Default: A preset clip (see background) (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"gameplaySpeed":{"description":"Gameplay speed: How fast the background footage plays.\nChoices:\n- 0.5 — 0.5x: Slow motion.\n- 0.75 — 0.75x: Slower.\n- 1 — 1x: Normal speed.\n- 1.25 — 1.25x: Faster.\n- 1.5 — 1.5x: Fast.\n- 2 — 2x: Double speed.\nDefault: 1.\nSend the value as text (\"1.25\") or a number (1.25).","anyOf":[{"description":"Gameplay speed: How fast the background footage plays.\nChoices:\n- 0.5 — 0.5x: Slow motion.\n- 0.75 — 0.75x: Slower.\n- 1 — 1x: Normal speed.\n- 1.25 — 1.25x: Faster.\n- 1.5 — 1.5x: Fast.\n- 2 — 2x: Double speed.\nDefault: 1.","type":"string","enum":["1","2","0.5","0.75","1.25","1.5"]},{"type":"number","enum":[0.5,0.75,1,1.25,1.5,2]}]},"music":{"title":"Background music (Character Explainer option music)","description":"Background music: The music under the voices: none, one of the app's soundtracks, or a mood (a track of that mood is picked for you, as automations do). The copyright-free AutoClips library tracks are in musicLibraryTrack; send one or the other. Free.\nOne of 240 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=ce&option=music) to see them all.\nChoices:\n- none — No music: Voices only.\n- mood:popular — Popular (picked for you): Fan-favorite tracks — deep, dramatic, and atmospheric vibes. A track of this mood is picked for the video.\n- mood:playful — Playful & Fun (picked for you): Light, quirky, comedic — perfect for funny educational content. A track of this mood is picked for the video.\n- mood:sneaky — Sneaky & Curious (picked for you): Tip-toeing, mischievous, investigative vibes. A track of this mood is picked for the video.\n- mood:mysterious — Mysterious & Dark (picked for you): Eerie, suspenseful, atmospheric tension. A track of this mood is picked for the video.\n- mood:epic — Epic & Dramatic (picked for you): Cinematic, powerful, building intensity. A track of this mood is picked for the video.\n- mood:chill — Chill & Calm (picked for you): Relaxed, dreamy, gentle background. A track of this mood is picked for the video.\n- mood:upbeat — Upbeat & Energetic (picked for you): Bouncy, lively, feel-good energy. A track of this mood is picked for the video.\n- mood:whimsical — Whimsical & Weird (picked for you): Absurd, circus-like, chaotic fun. A track of this mood is picked for the video.\n- mood:v3-animals — Animals & Wildlife, copyright-free (picked for you): Nature documentaries, wildlife. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-crime — Crime & Mystery, copyright-free (picked for you): Dark, suspenseful, investigative. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-general — General, copyright-free (picked for you): Versatile tracks for any topic. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-history — History, copyright-free (picked for you): Historical, documentary, period. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-horror — Horror, copyright-free (picked for you): Dark, terrifying, dread. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-science — Science, copyright-free (picked for you): Documentary, educational, wonder. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-space — Space & Cosmos, copyright-free (picked for you): Ethereal, cosmic, vast. A copyright-free AutoClips library track of this kind is picked for the video.\n- hide-and-sneak — Hide and Sneak: The Fly Guy Five. Popular soundtrack.\n- old-time-circus — Old Time Circus: Luella Gren. Popular soundtrack.\n- lurking-behind — Lurking Behind: The Fly Guy Five. Popular soundtrack.\n- ce-burning-memory — It's Just a Burning Memory: The Caretaker. Popular soundtrack.\n- ce-f-down — F.Down: Unknown. Popular soundtrack.\n- ce-school-rooftop — School Rooftop (Bird Sounds): hisohkah & WMD. Popular soundtrack.\n- ce-promise-reprise — Promise (Reprise): Unknown. Popular soundtrack.\n- ce-everything-in-its-right-place — Everything In Its Right Place (Instrumental): Radiohead. Popular soundtrack.\n- ce-six-forty-seven — Six Forty Seven: Instupendo. Popular soundtrack.\n- ce-numbers — Numbers (Instrumental): TEMPOREX. Popular soundtrack.\n- ce-fallen-down — Fallen Down (Panic Room): Undertale. Popular soundtrack.\n- ce-char-remix — Char (Remix) Slowed: Crystal Castles. Popular soundtrack.\n- ce-empathy — Empathy (Slowed + Reverb): Crystal Castles. Popular soundtrack.\n- ce-aleph — ALEPH (Slowed + Reverb): Gesaffelstein. Popular soundtrack.\n…and 210 more.\nDefault: none.","type":"string"},"musicLibraryTrack":{"title":"AutoClips library track (Character Explainer option musicLibraryTrack)","description":"AutoClips library track: One track of the copyright-free AutoClips music library, as the wizard's Music step lists it. Send it instead of music. Free.\nOne of 307 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=ce&option=musicLibraryTrack) to see them all.\nChoices:\n- v3-animals-wildlife-01-wild-kingdom-v1 — Wild Kingdom: Animals track: Upbeat, Nature, Documentary (2:16).\n- v3-animals-wildlife-01-wild-kingdom-v2 — Wild Kingdom: Animals track: Upbeat, Nature, Documentary (1:45).\n- v3-animals-wildlife-02-migration-path-v1 — Migration Path: Animals track: Sweeping, Cinematic, Emotional (2:53).\n- v3-animals-wildlife-02-migration-path-v2 — Migration Path: Animals track: Sweeping, Cinematic, Emotional (2:53).\n- v3-animals-wildlife-03-jungle-pulse-v1 — Jungle Pulse: Animals track: Rhythmic, Percussive, Tropical (1:22).\n- v3-animals-wildlife-03-jungle-pulse-v2 — Jungle Pulse: Animals track: Rhythmic, Percussive, Tropical (2:12).\n- v3-animals-wildlife-04-ocean-giants-v1 — Ocean Giants: Animals track: Majestic, Orchestral, Oceanic (3:55).\n- v3-animals-wildlife-04-ocean-giants-v2 — Ocean Giants: Animals track: Majestic, Orchestral, Oceanic (2:58).\n- v3-animals-wildlife-05-wings-of-freedom — Wings of Freedom: Animals track: Soaring, Cinematic, Uplifting (2:40).\n- v3-animals-wildlife-05-wings-of-freedom-v1 — Wings of Freedom: Animals track: Soaring, Cinematic, Uplifting (2:40).\n- v3-animals-wildlife-05-wings-of-freedom-v2 — Wings of Freedom: Animals track: Soaring, Cinematic, Uplifting (3:03).\n- v3-animals-01-predator-instinct — Predator Instinct: Animals track: Intense, Percussion, Primal (1:38).\n- v3-animals-02-coral-reef-dance — Coral Reef Dance: Animals track: Playful, Tropical, Underwater (2:05).\n- v3-animals-03-savanna-sunrise — Savanna Sunrise: Animals track: Warm, Acoustic, African (3:41).\n- v3-animals-04-arctic-whispers — Arctic Whispers: Animals track: Gentle, Ambient, Icy (2:54).\n- v3-animals-05-night-creatures — Night Creatures: Animals track: Mysterious, Nocturnal, Ambient (4:03).\n- v3-crime-mystery-01-cold-case-files-v1 — Cold Case Files: Crime track: Noir, Jazz, Detective (4:06).\n- v3-crime-mystery-01-cold-case-files-v2 — Cold Case Files: Crime track: Noir, Jazz, Detective (3:48).\n- v3-crime-mystery-02-under-surveillance-v1 — Under Surveillance: Crime track: Electronic, Thriller, Pulsing (5:08).\n- v3-crime-mystery-02-under-surveillance-v2 — Under Surveillance: Crime track: Electronic, Thriller, Pulsing (3:18).\n- v3-crime-mystery-03-the-investigation-v1 — The Investigation: Crime track: Dark, Detective, Piano (2:30).\n- v3-crime-mystery-03-the-investigation-v2 — The Investigation: Crime track: Dark, Detective, Piano (3:19).\n- v3-crime-mystery-04-hidden-evidence-v1 — Hidden Evidence: Crime track: Suspenseful, Ambient, Urgent (2:02).\n- v3-crime-mystery-04-hidden-evidence-v2 — Hidden Evidence: Crime track: Suspenseful, Ambient, Urgent (3:05).\n- v3-crime-mystery-05-midnight-pursuit-v1 — Midnight Pursuit: Crime track: Intense, Chase, Electronic (3:12).\n- v3-crime-mystery-05-midnight-pursuit-v2 — Midnight Pursuit: Crime track: Intense, Chase, Electronic (3:40).\n- v3-crime-01-blood-trail — Blood Trail: Crime track: Gritty, Electronic, Dark, Bass (3:45).\n- v3-crime-02-alibi-unraveled — Alibi Unraveled: Crime track: Tense, Piano, Thriller (1:55).\n- v3-crime-03-forensic-mind — Forensic Mind: Crime track: Clinical, Synth, Procedural (2:48).\n- v3-crime-04-double-cross — Double Cross: Crime track: Jazzy, Noir, Suspenseful (3:13).\n…and 277 more.\nDefault: No library track (see music) (leave it out).","type":"string"},"musicVolume":{"description":"Music volume: How loud the music is under the voices, from 0 (silent) to 1 (full). From 0 to 1, in steps of 0.01. Default: 0.15.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"showCaptions":{"description":"Captions: Show the spoken words on screen. Default: true.","type":"boolean"},"captionFont":{"description":"Caption font: The font of the captions.\nChoices:\n- BebasNeue — Bebas Neue: Bebas Neue lettering.\n- Anton — Anton: Anton lettering.\n- Montserrat — Montserrat: Montserrat lettering.\n- LeagueSpartan — League Spartan: League Spartan lettering.\nDefault: BebasNeue.","type":"string","enum":["BebasNeue","Anton","Montserrat","LeagueSpartan"]},"captionSizeMultiplier":{"description":"Caption size: How big the captions are: 1 is normal. From 0.7 to 1.5, in steps of 0.05. Default: 1.","type":"number","minimum":0.7,"maximum":1.5,"multipleOf":0.05},"captionVerticalPosition":{"description":"Caption height: Where the captions sit, in percent of the frame from the top. From 5 to 85 percent. Default: 44.","type":"integer","minimum":5,"maximum":85},"captionColor":{"description":"Caption colour: The colour of the words not being spoken, as #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"captionHighlightColor":{"description":"Caption highlight colour: The colour of the word being spoken, as #RRGGBB. Default: #FFD700.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"captionStrokeColor":{"description":"Caption outline colour: The colour of the outline around the words, as #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"characterSizeMultiplier":{"description":"Character size: How big the characters are on screen: 1 is normal, 0.3 is 30 percent, 2 is double. From 0.3 to 2, in steps of 0.05. Default: 1.","type":"number","minimum":0.3,"maximum":2,"multipleOf":0.05},"characterFloating":{"description":"Floating characters: A smooth idle wobble on the characters. Default: false.","type":"boolean"},"floatingIntensity":{"description":"Floating strength: How strong the wobble is, from subtle (0) to dramatic (100). Used when floating is on. From 0 to 100 percent, in steps of 5. Default: 50.","type":"integer","minimum":0,"maximum":100,"multipleOf":5},"watermarkType":{"description":"Watermark: A mark on the finished video: your text or your picture. Free videos also carry a small \"Made with Autoclips.app\" badge, whatever you pick here; a paid plan removes it.\nChoices:\n- none — None: No watermark of your own (a free video still carries the \"Made with Autoclips.app\" badge).\n- text — Text: Your handle or brand name as text (watermarkText).\n- image — Picture: Your logo from your media library (watermarkMediaId).\nDefault: none.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"Watermark text: The text of a text watermark. Default: No text (leave it out).","type":"string","minLength":1,"maxLength":50},"watermarkTextColor":{"description":"Watermark text colour: The colour of a text watermark, as #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundColor":{"description":"Watermark background colour: The colour of the box behind a text watermark, as #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundOpacity":{"description":"Watermark background opacity: How solid the box behind a text watermark is, from 0 (none) to 1 (solid). From 0 to 1, in steps of 0.01. Default: 0.5.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"watermarkMediaId":{"description":"For a picture watermark: one of your pictures from your media library (autoclips_media). A media id: 24 letters and digits. Default: No picture (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"watermarkImageOpacity":{"description":"Watermark picture opacity: How solid a picture watermark is, from 0.3 to 1 (solid). From 0.3 to 1, in steps of 0.01. Default: 0.7.","type":"number","minimum":0.3,"maximum":1,"multipleOf":0.01},"watermarkVerticalPosition":{"description":"Watermark height: Where the watermark sits, in percent of the frame from the top. From 10 to 90 percent. Default: 85.","type":"integer","minimum":10,"maximum":90},"watermarkHorizontalPosition":{"description":"Watermark across: Where the watermark sits, in percent of the frame from the left. From 5 to 95 percent. Default: 85.","type":"integer","minimum":5,"maximum":95},"watermarkScale":{"description":"Watermark size: How big the watermark is: 1 is normal, from 0.5 to 3. From 0.5 to 3, in steps of 0.01. Default: 1.","type":"number","minimum":0.5,"maximum":3,"multipleOf":0.01},"visualMode":{"description":"Visual style: What plays behind the characters. Motion graphics are designed for each scene and cost extra, by length.\nChoices:\n- gameplay — Gameplay: Classic: game footage behind your character.\n- motion-top — Motion graphics, top: Animated slides in the top panel, gameplay behind. (Adds 550 (30 seconds), 850 (1 minute), 1100 (1.5 minutes), 1400 (2 minutes), 2000 (3 minutes), 3600 (5 minutes) credits; plans: paid)\n- motion-full — Motion graphics, full screen: Full-screen animated slides, no gameplay. (Adds 550 (30 seconds), 850 (1 minute), 1100 (1.5 minutes), 1400 (2 minutes), 2000 (3 minutes), 3600 (5 minutes) credits; plans: paid)\nQuick Create makes gameplay videos only, so this can only be gameplay. Motion graphics (motion-top, motion-full) need a paid plan; to make one, make it step by step: ce_projects create with visualMode motion-top or motion-full, then ce_script generate, then ce_render start. Default: gameplay.","type":"string","enum":["gameplay","motion-top","motion-full"]},"characters":{"description":"One character talks alone; 2 to 6 talk to each other. A longer video holds more: up to 3 for 30 seconds, 4 for 1 minute, 5 for 1.5 minutes and 6 for 2 minutes or more (a length between two of these counts as the longer one). Pick each character by its slug from ce_characters list: built-in ones and your own.","minItems":1,"maxItems":6,"type":"array","items":{"type":"object","properties":{"character":{"description":"The character's slug from ce_characters list (or its exact name).","type":"string","minLength":1,"maxLength":120},"position":{"description":"Character position: Which corner a character stands in.\nChoices:\n- bottom-left — Bottom left: The character stands in the bottom left corner.\n- bottom-right — Bottom right: The character stands in the bottom right corner.\nDefault: Alternates, the first on the left (leave it out).","type":"string","enum":["bottom-left","bottom-right"]},"personality":{"description":"Character personality: The role a character plays in the conversation. Only one character is the lead (\"authority\"). When several would be, the first one you sent as \"authority\" keeps the role (if you sent none, the first one that is the lead by default), and the others become Skeptical Normies.\nChoices:\n- authority — Authority: The main character who sees the full picture, resolves tension.\n- naive-beginner — Naive Beginner: Asks basic questions everyone is thinking.\n- chaotic-zoomer — Chaotic Zoomer: Meme energy, half-informed but entertaining.\n- skeptical-normie — Skeptical Normie: Questions everything, healthy skepticism.\n- insider — Insider: Acts knowledgeable, implies hidden knowledge.\n- provocateur — Provocateur: Stirs controversy, pushes boundaries.\n- storyteller — Storyteller: Adds anecdotes, real-world examples.\n- comedian — Comedian: Turns everything into jokes, lightens mood.\n- philosopher — Philosopher: Goes deep, asks \"why\" behind everything.\n- hype-man — Hype Man: Gets excited, amplifies energy.\nDefault: The character's own default, else the lead (leave it out).","type":"string","enum":["authority","naive-beginner","chaotic-zoomer","skeptical-normie","insider","provocateur","storyteller","comedian","philosopher","hype-man"]}},"required":["character"],"additionalProperties":false}},"sceneImages":{"description":"Scene pictures: Pictures Quick Create makes for the scenes: none, real photos from the web, or a picture model. Charged per picture, for at most 6 pictures for 30 seconds, 10 pictures for 1 minute, 15 pictures for 1.5 minutes, 20 pictures for 2 minutes, 30 pictures for 3 minutes, 50 pictures for 5 minutes.\nChoices:\n- none — None: No scene pictures.\n- webSearch — Real photos: Real photos found on the web. (5 credits per picture; plans: paid)\n- ideogram2a — Ideogram 2.0a: Best quality, great for any content. (16 credits per picture; plans: paid)\n- recraftV3 — Recraft V3: High quality, versatile styles. (16 credits per picture; plans: paid)\n- zImageTurbo — Z-Image Turbo: Fast and inexpensive. (5 credits per picture; plans: paid)\n- fluxSchnell — Flux 2 Turbo: Excellent quality, fast. (12 credits per picture; plans: paid)\n- fluxDev — Flux Dev: Good quality. (12 credits per picture; plans: paid)\n- fluxPro — Flux 2 Pro: Premium quality. (16 credits per picture; plans: paid)\n- krea2Medium — Krea 2: Stunning aesthetics, rich artistic styles. (20 credits per picture; plans: paid)\n- nanoBanana2 — Nano Banana 2: Sharpest detail, best at following the prompt. (48 credits per picture; plans: paid)\n- grokImagine — Grok Imagine: Photoreal, relaxed about public figures. (10 credits per picture; plans: paid)\nDefault: none.","type":"string","enum":["none","webSearch","ideogram2a","recraftV3","zImageTurbo","fluxSchnell","fluxDev","fluxPro","krea2Medium","nanoBanana2","grokImagine"]},"sceneImageStyle":{"description":"Scene picture style: The look of the scene pictures Quick Create makes.\nChoices:\n- professional — Professional: A news or corporate look.\n- cinematic — Cinematic: Dramatic, movie-like.\n- aesthetic — Aesthetic: Trendy and beautiful.\n- educational — Educational: Clean and informative.\n- dramatic — Dramatic: High contrast, exposing.\n- meme — Meme: Internet humor.\nDefault: professional.","type":"string","enum":["professional","cinematic","aesthetic","educational","dramatic","meme"]},"soundEffects":{"description":"Sound effects: Quick Create picks a sound effect for each scene. Free. Default: false.","type":"boolean"},"reviewScript":{"description":"Review the script first: Quick Create stops after the script and waits for your OK (ce_script review) before it makes anything that costs credits. Default: false.","type":"boolean"},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["characters"],"additionalProperties":false},"example":{"topic":"How do black holes form?","characters":[{"character":"peter-griffin"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job":{"description":"Follow it with autoclips_jobs (GET /jobs/{id}) until the video is ready. While the script waits for your OK it says so in its step; ce_script review then answers with a new job for the rest.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"project":{"description":"The new project.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"ce"},"title":{"type":"string"},"status":{"description":"Where the project is: draft, writing_script, script_ready, needs_speakers, waiting_for_approval, making, prepared_in_app, finished, no_video, failed, stalled.","type":"string","enum":["draft","writing_script","script_ready","needs_speakers","waiting_for_approval","making","prepared_in_app","finished","no_video","failed","stalled"]},"statusText":{"description":"The status in plain words.","type":"string"},"step":{"description":"What is being made right now, while status is making.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"type":"number"},"revision":{"description":"Send it back as expectedRevision when you change scenes.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"appLink":{"description":"Where to open the project in the app.","type":"string"},"autoPost":{"description":"Where a finished render posts itself.","type":"object","properties":{"platforms":{"type":"array","items":{"type":"string"}}},"required":["platforms"],"additionalProperties":{}},"nextStep":{"description":"What to do next, in plain words.","type":"string"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","product","title","status","statusText","step","progress","revision","appLink","autoPost","nextStep","createdAt","updatedAt"],"additionalProperties":{}},"continued":{"description":"True when this call carried on a Quick Create that an earlier try of the same request already started (that try failed after the start, so its answer was lost). Nothing new was started: the job is that run's.","type":"boolean"},"notes":{"description":"What was changed from what you sent, and what the plan adds, in plain words (for example the length and the \"Made with Autoclips.app\" badge on a free plan). Tell the user.","type":"array","items":{"type":"string"}}},"required":["job","project","continued","notes"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"job":{"id":"job_019ad7c3f0e8a1b2c3d4e5f6","product":"ce","kind":"ce.quick_create","resource":{"type":"project","id":"9b2f4c1e-5d7a-4e3b-8c6f-1a2b3c4d5e6f"},"status":"queued","step":"Writing the script","progress":null,"result":null,"error":null,"createdAt":"2026-10-12T09:00:00.000Z","updatedAt":"2026-10-12T09:00:00.000Z","finishedAt":null,"poll_after_seconds":15,"usualSeconds":450},"project":{"id":"9b2f4c1e-5d7a-4e3b-8c6f-1a2b3c4d5e6f","product":"ce","title":"How do black holes form?","status":"making","statusText":"Being made: Writing script (5%).","step":"Writing script","progress":5,"revision":1791795600000,"appLink":"https://app.autoclips.app/character-explainer?sessionId=9b2f4c1e-5d7a-4e3b-8c6f-1a2b3c4d5e6f","autoPost":{"platforms":[]},"nextStep":"Wait for the video: follow its job with autoclips_jobs, or read the project again.","createdAt":"2026-10-12T09:00:00.000Z","updatedAt":"2026-10-12T09:00:00.000Z","characters":[{"slug":"peter-griffin","name":"Peter Griffin","position":"bottom-left","personality":"authority","builtIn":true,"pictureUrl":"https://media.autoclips.app/characters/peter.png"}]},"continued":false,"notes":[]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/projects/{projectId}":{"patch":{"operationId":"ce_projects_update","summary":"Change a Character Explainer draft's settings or characters. Only what you send changes.","description":"Changes only the settings you send, in the same words create takes (autoclips_options, product ce). Free.\nOnly a draft can change: not while the script is being written, the pictures are being made or the video is being made, and not once it is finished. A failed project is put back to a draft first, so you can fix it and render again.\ncharacters replaces the whole cast (the same rules as create: up to the length's number of characters, each able to speak the language). A new length or language must still suit the cast you keep.\nbackground picks a preset clip and stops using your own clip; gameplayMediaId uses one of your videos instead. A new length (or a new pasted script, which can make the video longer than the length picked) keeps the preset clip while it is long enough; a shorter one is swapped for a clip that fits, and the notes say so. musicVolume alone changes the volume of the saved music. Watermark fields change only what you send and keep the rest.\noutroId none takes the outro off; characterPlacementX and characterPlacementY sent as null put the character back in its corner.\nSwitching to motion graphics, or a motion graphics video's Motion sound effects to auto or off, takes the sound effects off its scenes (the video then makes its own, or has none, and the render would play the scene ones on top; the app takes them off the same way when its Motion sound effects is set to auto or off); the notes say so.\nChanging the length, characters, language, style or topic after the script was written keeps the script: the notes say so, and ce_script generate (replace: true) writes a new one.\nWith a script, the scenes said by characters who are not in the new cast go to it, the way the app gives them out when it makes the voices (each one that left, in the order it first speaks, to the next character of the new cast in turn; where one voice reads every scene, all to the first character); the notes say who went where, and which scenes still name a character who left in their words. Sending the same cast again does this for scenes a cast change in the app left behind.\nFree plans make 30-second videos, paid for from the 150 credits a new account gets, and every free video carries a small \"Made with Autoclips.app\" badge (with as many characters as 30 seconds hold); your own script, the Trending, Quality and Ultra scripts, motion graphics and an outro need a paid plan.\nThe answer shows the project and what rendering it will cost now (price).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"ce.projects.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_projects action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputMode":{"description":"What the script comes from: Write the script from a topic, or use a script you paste.\nChoices:\n- topic — Topic: The AI writes the script from your topic.\n- custom_script — Your script: Your own script, split into scenes and voiced as written. (Billed at the longer of the length you pick and how long your script takes to say (about 500 characters per 30 seconds; speaker names are not counted); plans: paid)\nDefault: the project's saved choice (leave it out).","type":"string","enum":["topic","custom_script"]},"topic":{"description":"Topic: What the video is about, in your words (research notes and links are fine). A web link in it is read from the web while the script is written; a link to a private or internal address is refused. Default: the project's saved choice (leave it out).","type":"string","minLength":1,"maxLength":5000},"customScript":{"description":"Your script: The script to use, for \"Your script\" (inputMode custom_script). It sets the billed length: about 500 spoken characters per 30 seconds, never less than the length you pick. Speaker names (\"Peter:\"), markdown and blank lines are not counted; Japanese, Chinese, Thai and Korean count at their own speaking pace, and a script that takes longer than 5 minutes to say is refused. Default: the project's saved choice (leave it out).","type":"string","minLength":20,"maxLength":5000},"style":{"description":"Style: How the script is written.\nChoices:\n- explainer — Explainer: Show how something really works.\n- controversy — Controversy: Lay out a case, exhibit by exhibit.\n- educational — Educational: Teach something new.\n- funny — Comedy: Make them laugh.\n- storytelling — Story: Tell a story.\n- brainrot — Brain Rot: Gen Z chaos mode: fast, loud and full of slang.\nDefault: the project's saved choice (leave it out).","type":"string","enum":["explainer","controversy","educational","funny","storytelling","brainrot"]},"durationSeconds":{"description":"How long the video is meant to be. It is billed at the price band it rounds up to (30, 60, 90, 120, 180 or 300 seconds): a 40-second video costs what a 1-minute one does. Free plans make 30-second videos: a longer length is set to 30 seconds, with a note. Send it as a number (60); its id as text (\"60\") is taken too. One of 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 180, 240, 300 seconds. Default: the project's saved choice (leave it out).","anyOf":[{"type":"number","enum":[30,40,50,60,70,80,90,100,110,120,180,240,300]},{"type":"string","pattern":"^(?:30|40|50|60|70|80|90|100|110|120|180|240|300)$"}]},"language":{"title":"Language (Character Explainer option language)","description":"Language: The language of the script, the voices and the captions. Every character in the video must be able to speak it (ce_characters list shows which can).\nOne of 94 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=ce&option=language) to see them all.\nChoices:\n- en — English: English script, voices and captions.\n- es — Spanish: Spanish script, voices and captions.\n- pt — Portuguese: Portuguese script, voices and captions.\n- fr — French: French script, voices and captions.\n- de — German: German script, voices and captions.\n- hi — Hindi: Hindi script, voices and captions.\n- ar — Arabic: Arabic script, voices and captions.\n- ja — Japanese: Japanese script, voices and captions.\n- zh — Chinese: Chinese script, voices and captions.\n- id — Indonesian: Indonesian script, voices and captions.\n- ru — Russian: Russian script, voices and captions.\n- tr — Turkish: Turkish script, voices and captions.\n- ko — Korean: Korean script, voices and captions.\n- it — Italian: Italian script, voices and captions.\n- nl — Dutch: Dutch script, voices and captions.\n- pl — Polish: Polish script, voices and captions.\n- ro — Romanian: Romanian script, voices and captions.\n- cs — Czech: Czech script, voices and captions.\n- sk — Slovak: Slovak script, voices and captions.\n- hu — Hungarian: Hungarian script, voices and captions.\n- sv — Swedish: Swedish script, voices and captions.\n- da — Danish: Danish script, voices and captions.\n- no — Norwegian: Norwegian script, voices and captions.\n- fi — Finnish: Finnish script, voices and captions.\n- is — Icelandic: Icelandic script, voices and captions.\n- et — Estonian: Estonian script, voices and captions.\n- lv — Latvian: Latvian script, voices and captions.\n- lt — Lithuanian: Lithuanian script, voices and captions.\n- el — Greek: Greek script, voices and captions.\n- bg — Bulgarian: Bulgarian script, voices and captions.\n…and 64 more.\nDefault: the project's saved choice (leave it out).","type":"string"},"scriptMode":{"description":"Script quality: Which writer makes the script. It sets the video price, by length.\nChoices:\n- normal — Normal: Quick, solid scripts for subjects that do not change: how-tos, explainers, timeless facts. (50 (30 seconds), 50 (1 minute), 100 (1.5 minutes), 200 (2 minutes), 300 (3 minutes), 500 (5 minutes) credits)\n- max — Trending: Looks the topic up on the web as it writes, so it can use real facts from this week. For news, launches and anything happening right now. (100 (30 seconds), 100 (1 minute), 200 (1.5 minutes), 300 (2 minutes), 450 (3 minutes), 750 (5 minutes) credits; plans: paid)\n- pro — Quality: The most polished writing: stronger hooks, better pacing, endings that land. No web search. (100 (30 seconds), 100 (1 minute), 200 (1.5 minutes), 300 (2 minutes), 450 (3 minutes), 750 (5 minutes) credits; plans: paid)\n- ultra — Ultra: The strongest writing plus live web research: the best script we can make, whatever the topic. (200 (30 seconds), 200 (1 minute), 300 (1.5 minutes), 400 (2 minutes), 600 (3 minutes), 1000 (5 minutes) credits; plans: paid)\nDefault: the project's saved choice (leave it out).","type":"string","enum":["normal","max","pro","ultra"]},"customInstructions":{"description":"Extra instructions: Anything the writer should keep in mind (tone, audience, a call to action). The wizard has no box for it; automations and the original AI tool use it. Default: the project's saved choice (leave it out).","type":"string","minLength":1,"maxLength":1000},"characterPlacementX":{"description":"Character placement, across: Where the character stands, in percent of the frame from the left, when you move it off its corner (the Preview step's Move character). Send it with characterPlacementY. An update that sends null for both characterPlacementX and characterPlacementY puts the character back in its corner. From 5 to 95 percent. Default: the project's saved choice (leave it out).","anyOf":[{"description":"Character placement, across: Where the character stands, in percent of the frame from the left, when you move it off its corner (the Preview step's Move character). Send it with characterPlacementY. An update that sends null for both characterPlacementX and characterPlacementY puts the character back in its corner. From 5 to 95 percent. Default: the project's saved choice (leave it out).","type":"integer","minimum":5,"maximum":95},{"type":"null"}]},"characterPlacementY":{"description":"Character placement, down: Where the character stands, in percent of the frame from the top. Send it with characterPlacementX. An update that sends null for both characterPlacementX and characterPlacementY puts the character back in its corner. From 20 to 100 percent. Default: the project's saved choice (leave it out).","anyOf":[{"description":"Character placement, down: Where the character stands, in percent of the frame from the top. Send it with characterPlacementX. An update that sends null for both characterPlacementX and characterPlacementY puts the character back in its corner. From 20 to 100 percent. Default: the project's saved choice (leave it out).","type":"integer","minimum":20,"maximum":100},{"type":"null"}]},"characterSizeMultiplier":{"description":"Character size: How big the characters are on screen: 1 is normal, 0.3 is 30 percent, 2 is double. From 0.3 to 2, in steps of 0.05. Default: the project's saved choice (leave it out).","type":"number","minimum":0.3,"maximum":2,"multipleOf":0.05},"characterFloating":{"description":"Floating characters: A smooth idle wobble on the characters. Default: the project's saved choice (leave it out).","type":"boolean"},"floatingIntensity":{"description":"Floating strength: How strong the wobble is, from subtle (0) to dramatic (100). Used when floating is on. From 0 to 100 percent, in steps of 5. Default: the project's saved choice (leave it out).","type":"integer","minimum":0,"maximum":100,"multipleOf":5},"ttsModel":{"description":"Voice model: Which voice model speaks the lines. A new project starts on your account's voice model (the one you last picked in the app, shared with V3), or Eleven v4 if you never picked one.\nChoices:\n- eleven_v4 — Eleven v4: Recommended. The newest model, best for every language.\n- eleven_v3 — Eleven v3: An older model. Some cloned cartoon voices sound more natural on it.\n- eleven_multilingual_v2 — Multilingual v2: An older model with a steady read. What Character Explainer spoke before.\nDefault: the project's saved choice (leave it out).","type":"string","enum":["eleven_v4","eleven_v3","eleven_multilingual_v2"]},"voiceEmotion":{"description":"Voice emotion: How much emotion the voices carry.\nChoices:\n- off — Off: A neutral, steady tone throughout.\n- subtle — Subtle: Light emotion: hooks sound a little more engaging.\n- normal — Normal: Emotion from the context: hooks are exciting, questions are curious.\n- expressive — Expressive: Strong emotion, for entertainment and comedy.\nDefault: the project's saved choice (leave it out).","type":"string","enum":["off","subtle","normal","expressive"]},"speechSpeed":{"description":"Speech speed: How fast the characters talk: 1 is normal, 1.15 is a little quicker for better pacing. From 0.75 to 1.5, in steps of 0.05. Default: the project's saved choice (leave it out).","type":"number","minimum":0.75,"maximum":1.5,"multipleOf":0.05},"overrideSpeechSpeed":{"description":"Same speed for everyone: On: every character talks at the speech speed, ignoring their own speed settings. Off: characters with their own speed keep it. Default: the project's saved choice (leave it out).","type":"boolean"},"visualMode":{"description":"Visual style: What plays behind the characters. Motion graphics are designed for each scene and cost extra, by length.\nChoices:\n- gameplay — Gameplay: Classic: game footage behind your character.\n- motion-top — Motion graphics, top: Animated slides in the top panel, gameplay behind. (Adds 550 (30 seconds), 850 (1 minute), 1100 (1.5 minutes), 1400 (2 minutes), 2000 (3 minutes), 3600 (5 minutes) credits; plans: paid)\n- motion-full — Motion graphics, full screen: Full-screen animated slides, no gameplay. (Adds 550 (30 seconds), 850 (1 minute), 1100 (1.5 minutes), 1400 (2 minutes), 2000 (3 minutes), 3600 (5 minutes) credits; plans: paid)\nDefault: the project's saved choice (leave it out).","type":"string","enum":["gameplay","motion-top","motion-full"]},"motionTheme":{"description":"Slide theme: The colours of the motion graphics slides. Motion graphics only.\nChoices:\n- auto — Auto: The art director picks the slide colours for the topic.\n- dark — Dark: Light words on dark slides.\n- cream — Cream: Dark words on warm cream slides. What a new project starts on.\nDefault: the project's saved choice (leave it out).","type":"string","enum":["auto","dark","cream"]},"motionCaptionStyle":{"description":"Motion caption style: How the words are printed on a motion graphics video. Motion graphics only.\nChoices:\n- classic — Classic: Big stroked words. The default.\n- boxed — Boxed: A white card with two-tone read-along words, like the clean explainer reels.\nDefault: the project's saved choice (leave it out).","type":"string","enum":["classic","boxed"]},"motionAuthorModel":{"description":"Slide designer: Which AI writes the motion graphics scenes. Its price is the motion graphics surcharge. Motion graphics only.\nChoices:\n- standard — Gemini 3.8 Flash: Fastest to build and the lowest cost per scene. (Adds 550 (30 seconds), 850 (1 minute), 1100 (1.5 minutes), 1400 (2 minutes), 2000 (3 minutes), 3600 (5 minutes) credits)\nDefault: the project's saved choice (leave it out).","type":"string","enum":["standard"]},"intelligentVisualSourcing":{"description":"Real pictures in the slides: Let the slide designer add real or generated pictures where a picture explains better than line art. Not charged when the video is made from the wizard or this API. Motion graphics only. Default: the project's saved choice (leave it out).","type":"boolean"},"motionAssetModel":{"description":"Slide picture maker: Which model makes the pictures for the slides. Not charged when the video is made from the wizard or this API. Motion graphics only.\nChoices:\n- nanoBanana2 — Nano Banana 2: Best overall quality for polished, topic-specific visuals.\n- grokImagine — Grok Imagine: Bold, imaginative compositions for story-led explainers.\n- fluxSchnell — Flux 2 Turbo: Quick generation for simple supporting visuals.\n- fluxDev — Flux Dev: A balance of detail, speed, and prompt accuracy.\n- fluxPro — Flux Pro: Detailed output for complex explanatory visuals.\nDefault: the project's saved choice (leave it out).","type":"string","enum":["nanoBanana2","grokImagine","fluxSchnell","fluxDev","fluxPro"]},"motionAssetTier":{"description":"How many slide pictures: The most real or generated pictures the slides may use. Motion graphics only.\nChoices:\n- none — None: Hand-drawn graphics only.\n- balanced — Balanced: Up to 3 sourced images where a picture explains better than line art.\n- rich — Rich: Up to 6 sourced images. Best for longer videos with more to show.\nDefault: the project's saved choice (leave it out).","type":"string","enum":["none","balanced","rich"]},"motionSoundDesign":{"description":"Motion sound design: How loud the beat-timed sound design is. Motion graphics only.\nChoices:\n- subtle — Subtle: Soft ticks and whooshes under the voice, plus a quiet music bed.\n- punchy — Punchy: Louder hits on every beat and cut for high-energy topics.\n- off — Off: Narration and your chosen music only.\nDefault: the project's saved choice (leave it out).","type":"string","enum":["subtle","punchy","off"]},"motionMusicMode":{"description":"Motion music: Where the music of a motion graphics video comes from. Motion graphics only.\nChoices:\n- auto — Auto: We score it for you.\n- track — My track: A track you pick (see music).\n- off — Off: No music at all.\nDefault: the project's saved choice (leave it out).","type":"string","enum":["auto","track","off"]},"motionSfxMode":{"description":"Motion sound effects: Where the sound effects of a motion graphics video come from. Motion graphics only.\nChoices:\n- auto — Auto: Timed to the motion and every cut.\n- library — From library: One effect per scene from the library, picked in the app (through the API, scene sound effects are set on gameplay videos only).\n- off — Off: No sound effects.\nDefault: the project's saved choice (leave it out).","type":"string","enum":["auto","library","off"]},"background":{"title":"Gameplay background (Character Explainer option background)","description":"Gameplay background: The game footage behind the characters: a game (one of its clips at least as long as the video is picked), \"random\" for any game, or one exact clip at least as long as the video. A preset clip does not repeat, so a game whose clips are all shorter than the video, or a shorter clip, is refused. Leave it out for a Minecraft clip that fits. To use your own clip, send gameplayMediaId instead.\nOne of 106 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=ce&option=background) to see them all.\nChoices:\n- random — Any game: A clip from any game, at least as long as the video.\n- minecraft — Minecraft: A Minecraft clip at least as long as the video. Its clips run up to 5 minutes, so it fits a video up to that long.\n- roblox — Roblox: A Roblox clip at least as long as the video. Its clips run up to 3 minutes, so it fits a video up to that long.\n- gta — GTA: A GTA clip at least as long as the video. Its clips run up to 3 minutes, so it fits a video up to that long.\n- subway — Subway Surfers: A Subway Surfers clip at least as long as the video. Its clips run up to 3 minutes, so it fits a video up to that long.\n- asmr — Satisfying: A Satisfying clip at least as long as the video. Its clips run up to 3 minutes, so it fits a video up to that long.\n- minecraft_part_0 — Minecraft 1 (1:30): Minecraft gameplay, 90 seconds long.\n- minecraft_part_1 — Minecraft 2 (1:15): Minecraft gameplay, 75 seconds long.\n- minecraft_part_2 — Minecraft 3 (1:45): Minecraft gameplay, 105 seconds long.\n- minecraft_part_3 — Minecraft 4 (1:00): Minecraft gameplay, 60 seconds long.\n- minecraft_part_4 — Minecraft 5 (2:00): Minecraft gameplay, 120 seconds long.\n- minecraft_part_5 — Minecraft 6 (1:30): Minecraft gameplay, 90 seconds long.\n- minecraft_part_6 — Minecraft 7 (2:00): Minecraft gameplay, 120 seconds long.\n- minecraft_new_1 — Parkour 1 (2:00): Minecraft gameplay, 120 seconds long.\n- minecraft_new_2 — Parkour 2 (1:30): Minecraft gameplay, 90 seconds long.\n- minecraft_new_3 — Parkour 3 (2:00): Minecraft gameplay, 120 seconds long.\n- minecraft_new_4 — Parkour 4 (1:30): Minecraft gameplay, 90 seconds long.\n- minecraft_new_5 — Parkour 5 (2:30): Minecraft gameplay, 150 seconds long.\n- minecraft_new_6 — Parkour 6 (2:00): Minecraft gameplay, 120 seconds long.\n- minecraft_new_7 — Parkour 7 (1:30): Minecraft gameplay, 90 seconds long.\n- minecraft_new_8 — Parkour 8 (3:05): Minecraft gameplay, 185 seconds long.\n- parkour_v2_1_01_90s — V2 1-1 (1:30): Minecraft gameplay, 90 seconds long.\n- parkour_v2_1_02_180s — V2 1-2 (3:00): Minecraft gameplay, 180 seconds long.\n- parkour_v2_1_03_300s — V2 1-3 (5:00): Minecraft gameplay, 300 seconds long.\n- parkour_v2_1_04_90s — V2 1-4 (1:30): Minecraft gameplay, 90 seconds long.\n- parkour_v2_1_05_180s — V2 1-5 (3:00): Minecraft gameplay, 180 seconds long.\n- parkour_v2_1_06_114s — V2 1-6 (1:54): Minecraft gameplay, 114 seconds long.\n- parkour_v2_2_01_90s — V2 2-1 (1:30): Minecraft gameplay, 90 seconds long.\n- parkour_v2_2_02_180s — V2 2-2 (3:00): Minecraft gameplay, 180 seconds long.\n- parkour_v2_3_01_90s — V2 3-1 (1:30): Minecraft gameplay, 90 seconds long.\n…and 76 more.\nDefault: the project's saved choice (leave it out).","type":"string"},"gameplayMediaId":{"description":"One of your videos (MP4, WebM or MOV) from your media library (autoclips_media), played behind the characters instead of a preset clip. A media id: 24 letters and digits. Default: the project's saved choice (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"gameplaySpeed":{"description":"Gameplay speed: How fast the background footage plays.\nChoices:\n- 0.5 — 0.5x: Slow motion.\n- 0.75 — 0.75x: Slower.\n- 1 — 1x: Normal speed.\n- 1.25 — 1.25x: Faster.\n- 1.5 — 1.5x: Fast.\n- 2 — 2x: Double speed.\nDefault: the project's saved choice (leave it out).\nSend the value as text (\"1.25\") or a number (1.25).","anyOf":[{"description":"Gameplay speed: How fast the background footage plays.\nChoices:\n- 0.5 — 0.5x: Slow motion.\n- 0.75 — 0.75x: Slower.\n- 1 — 1x: Normal speed.\n- 1.25 — 1.25x: Faster.\n- 1.5 — 1.5x: Fast.\n- 2 — 2x: Double speed.\nDefault: the project's saved choice (leave it out).","type":"string","enum":["1","2","0.5","0.75","1.25","1.5"]},{"type":"number","enum":[0.5,0.75,1,1.25,1.5,2]}]},"music":{"title":"Background music (Character Explainer option music)","description":"Background music: The music under the voices: none, one of the app's soundtracks, or a mood (a track of that mood is picked for you, as automations do). The copyright-free AutoClips library tracks are in musicLibraryTrack; send one or the other. Free.\nOne of 240 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=ce&option=music) to see them all.\nChoices:\n- none — No music: Voices only.\n- mood:popular — Popular (picked for you): Fan-favorite tracks — deep, dramatic, and atmospheric vibes. A track of this mood is picked for the video.\n- mood:playful — Playful & Fun (picked for you): Light, quirky, comedic — perfect for funny educational content. A track of this mood is picked for the video.\n- mood:sneaky — Sneaky & Curious (picked for you): Tip-toeing, mischievous, investigative vibes. A track of this mood is picked for the video.\n- mood:mysterious — Mysterious & Dark (picked for you): Eerie, suspenseful, atmospheric tension. A track of this mood is picked for the video.\n- mood:epic — Epic & Dramatic (picked for you): Cinematic, powerful, building intensity. A track of this mood is picked for the video.\n- mood:chill — Chill & Calm (picked for you): Relaxed, dreamy, gentle background. A track of this mood is picked for the video.\n- mood:upbeat — Upbeat & Energetic (picked for you): Bouncy, lively, feel-good energy. A track of this mood is picked for the video.\n- mood:whimsical — Whimsical & Weird (picked for you): Absurd, circus-like, chaotic fun. A track of this mood is picked for the video.\n- mood:v3-animals — Animals & Wildlife, copyright-free (picked for you): Nature documentaries, wildlife. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-crime — Crime & Mystery, copyright-free (picked for you): Dark, suspenseful, investigative. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-general — General, copyright-free (picked for you): Versatile tracks for any topic. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-history — History, copyright-free (picked for you): Historical, documentary, period. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-horror — Horror, copyright-free (picked for you): Dark, terrifying, dread. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-science — Science, copyright-free (picked for you): Documentary, educational, wonder. A copyright-free AutoClips library track of this kind is picked for the video.\n- mood:v3-space — Space & Cosmos, copyright-free (picked for you): Ethereal, cosmic, vast. A copyright-free AutoClips library track of this kind is picked for the video.\n- hide-and-sneak — Hide and Sneak: The Fly Guy Five. Popular soundtrack.\n- old-time-circus — Old Time Circus: Luella Gren. Popular soundtrack.\n- lurking-behind — Lurking Behind: The Fly Guy Five. Popular soundtrack.\n- ce-burning-memory — It's Just a Burning Memory: The Caretaker. Popular soundtrack.\n- ce-f-down — F.Down: Unknown. Popular soundtrack.\n- ce-school-rooftop — School Rooftop (Bird Sounds): hisohkah & WMD. Popular soundtrack.\n- ce-promise-reprise — Promise (Reprise): Unknown. Popular soundtrack.\n- ce-everything-in-its-right-place — Everything In Its Right Place (Instrumental): Radiohead. Popular soundtrack.\n- ce-six-forty-seven — Six Forty Seven: Instupendo. Popular soundtrack.\n- ce-numbers — Numbers (Instrumental): TEMPOREX. Popular soundtrack.\n- ce-fallen-down — Fallen Down (Panic Room): Undertale. Popular soundtrack.\n- ce-char-remix — Char (Remix) Slowed: Crystal Castles. Popular soundtrack.\n- ce-empathy — Empathy (Slowed + Reverb): Crystal Castles. Popular soundtrack.\n- ce-aleph — ALEPH (Slowed + Reverb): Gesaffelstein. Popular soundtrack.\n…and 210 more.\nDefault: the project's saved choice (leave it out).","type":"string"},"musicLibraryTrack":{"title":"AutoClips library track (Character Explainer option musicLibraryTrack)","description":"AutoClips library track: One track of the copyright-free AutoClips music library, as the wizard's Music step lists it. Send it instead of music. Free.\nOne of 307 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=ce&option=musicLibraryTrack) to see them all.\nChoices:\n- v3-animals-wildlife-01-wild-kingdom-v1 — Wild Kingdom: Animals track: Upbeat, Nature, Documentary (2:16).\n- v3-animals-wildlife-01-wild-kingdom-v2 — Wild Kingdom: Animals track: Upbeat, Nature, Documentary (1:45).\n- v3-animals-wildlife-02-migration-path-v1 — Migration Path: Animals track: Sweeping, Cinematic, Emotional (2:53).\n- v3-animals-wildlife-02-migration-path-v2 — Migration Path: Animals track: Sweeping, Cinematic, Emotional (2:53).\n- v3-animals-wildlife-03-jungle-pulse-v1 — Jungle Pulse: Animals track: Rhythmic, Percussive, Tropical (1:22).\n- v3-animals-wildlife-03-jungle-pulse-v2 — Jungle Pulse: Animals track: Rhythmic, Percussive, Tropical (2:12).\n- v3-animals-wildlife-04-ocean-giants-v1 — Ocean Giants: Animals track: Majestic, Orchestral, Oceanic (3:55).\n- v3-animals-wildlife-04-ocean-giants-v2 — Ocean Giants: Animals track: Majestic, Orchestral, Oceanic (2:58).\n- v3-animals-wildlife-05-wings-of-freedom — Wings of Freedom: Animals track: Soaring, Cinematic, Uplifting (2:40).\n- v3-animals-wildlife-05-wings-of-freedom-v1 — Wings of Freedom: Animals track: Soaring, Cinematic, Uplifting (2:40).\n- v3-animals-wildlife-05-wings-of-freedom-v2 — Wings of Freedom: Animals track: Soaring, Cinematic, Uplifting (3:03).\n- v3-animals-01-predator-instinct — Predator Instinct: Animals track: Intense, Percussion, Primal (1:38).\n- v3-animals-02-coral-reef-dance — Coral Reef Dance: Animals track: Playful, Tropical, Underwater (2:05).\n- v3-animals-03-savanna-sunrise — Savanna Sunrise: Animals track: Warm, Acoustic, African (3:41).\n- v3-animals-04-arctic-whispers — Arctic Whispers: Animals track: Gentle, Ambient, Icy (2:54).\n- v3-animals-05-night-creatures — Night Creatures: Animals track: Mysterious, Nocturnal, Ambient (4:03).\n- v3-crime-mystery-01-cold-case-files-v1 — Cold Case Files: Crime track: Noir, Jazz, Detective (4:06).\n- v3-crime-mystery-01-cold-case-files-v2 — Cold Case Files: Crime track: Noir, Jazz, Detective (3:48).\n- v3-crime-mystery-02-under-surveillance-v1 — Under Surveillance: Crime track: Electronic, Thriller, Pulsing (5:08).\n- v3-crime-mystery-02-under-surveillance-v2 — Under Surveillance: Crime track: Electronic, Thriller, Pulsing (3:18).\n- v3-crime-mystery-03-the-investigation-v1 — The Investigation: Crime track: Dark, Detective, Piano (2:30).\n- v3-crime-mystery-03-the-investigation-v2 — The Investigation: Crime track: Dark, Detective, Piano (3:19).\n- v3-crime-mystery-04-hidden-evidence-v1 — Hidden Evidence: Crime track: Suspenseful, Ambient, Urgent (2:02).\n- v3-crime-mystery-04-hidden-evidence-v2 — Hidden Evidence: Crime track: Suspenseful, Ambient, Urgent (3:05).\n- v3-crime-mystery-05-midnight-pursuit-v1 — Midnight Pursuit: Crime track: Intense, Chase, Electronic (3:12).\n- v3-crime-mystery-05-midnight-pursuit-v2 — Midnight Pursuit: Crime track: Intense, Chase, Electronic (3:40).\n- v3-crime-01-blood-trail — Blood Trail: Crime track: Gritty, Electronic, Dark, Bass (3:45).\n- v3-crime-02-alibi-unraveled — Alibi Unraveled: Crime track: Tense, Piano, Thriller (1:55).\n- v3-crime-03-forensic-mind — Forensic Mind: Crime track: Clinical, Synth, Procedural (2:48).\n- v3-crime-04-double-cross — Double Cross: Crime track: Jazzy, Noir, Suspenseful (3:13).\n…and 277 more.\nDefault: the project's saved choice (leave it out).","type":"string"},"musicVolume":{"description":"Music volume: How loud the music is under the voices, from 0 (silent) to 1 (full). From 0 to 1, in steps of 0.01. Default: the project's saved choice (leave it out).","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"showCaptions":{"description":"Captions: Show the spoken words on screen. Default: the project's saved choice (leave it out).","type":"boolean"},"captionFont":{"description":"Caption font: The font of the captions.\nChoices:\n- BebasNeue — Bebas Neue: Bebas Neue lettering.\n- Anton — Anton: Anton lettering.\n- Montserrat — Montserrat: Montserrat lettering.\n- LeagueSpartan — League Spartan: League Spartan lettering.\nDefault: the project's saved choice (leave it out).","type":"string","enum":["BebasNeue","Anton","Montserrat","LeagueSpartan"]},"captionSizeMultiplier":{"description":"Caption size: How big the captions are: 1 is normal. From 0.7 to 1.5, in steps of 0.05. Default: the project's saved choice (leave it out).","type":"number","minimum":0.7,"maximum":1.5,"multipleOf":0.05},"captionVerticalPosition":{"description":"Caption height: Where the captions sit, in percent of the frame from the top. From 5 to 85 percent. Default: the project's saved choice (leave it out).","type":"integer","minimum":5,"maximum":85},"captionColor":{"description":"Caption colour: The colour of the words not being spoken, as #RRGGBB. Default: the project's saved choice (leave it out).","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"captionHighlightColor":{"description":"Caption highlight colour: The colour of the word being spoken, as #RRGGBB. Default: the project's saved choice (leave it out).","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"captionStrokeColor":{"description":"Caption outline colour: The colour of the outline around the words, as #RRGGBB. Default: the project's saved choice (leave it out).","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkType":{"description":"Watermark: A mark on the finished video: your text or your picture. Free videos also carry a small \"Made with Autoclips.app\" badge, whatever you pick here; a paid plan removes it.\nChoices:\n- none — None: No watermark of your own (a free video still carries the \"Made with Autoclips.app\" badge).\n- text — Text: Your handle or brand name as text (watermarkText).\n- image — Picture: Your logo from your media library (watermarkMediaId).\nDefault: the project's saved choice (leave it out).","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"Watermark text: The text of a text watermark. Default: the project's saved choice (leave it out).","type":"string","minLength":1,"maxLength":50},"watermarkTextColor":{"description":"Watermark text colour: The colour of a text watermark, as #RRGGBB. Default: the project's saved choice (leave it out).","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundColor":{"description":"Watermark background colour: The colour of the box behind a text watermark, as #RRGGBB. Default: the project's saved choice (leave it out).","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundOpacity":{"description":"Watermark background opacity: How solid the box behind a text watermark is, from 0 (none) to 1 (solid). From 0 to 1, in steps of 0.01. Default: the project's saved choice (leave it out).","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"watermarkMediaId":{"description":"For a picture watermark: one of your pictures from your media library (autoclips_media). A media id: 24 letters and digits. Default: the project's saved choice (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"watermarkImageOpacity":{"description":"Watermark picture opacity: How solid a picture watermark is, from 0.3 to 1 (solid). From 0.3 to 1, in steps of 0.01. Default: the project's saved choice (leave it out).","type":"number","minimum":0.3,"maximum":1,"multipleOf":0.01},"watermarkVerticalPosition":{"description":"Watermark height: Where the watermark sits, in percent of the frame from the top. From 10 to 90 percent. Default: the project's saved choice (leave it out).","type":"integer","minimum":10,"maximum":90},"watermarkHorizontalPosition":{"description":"Watermark across: Where the watermark sits, in percent of the frame from the left. From 5 to 95 percent. Default: the project's saved choice (leave it out).","type":"integer","minimum":5,"maximum":95},"watermarkScale":{"description":"Watermark size: How big the watermark is: 1 is normal, from 0.5 to 3. From 0.5 to 3, in steps of 0.01. Default: the project's saved choice (leave it out).","type":"number","minimum":0.5,"maximum":3,"multipleOf":0.01},"outroId":{"description":"Outro: An end card from your outros (autoclips_outros) added after the last scene. Paid plans only: on a free plan it is refused with plan_required. Send \"none\" for no outro: on a new project that is the same as leaving it out, and an update takes the saved outro off. Default: the project's saved choice (leave it out).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"characters":{"description":"One character talks alone; 2 to 6 talk to each other. A longer video holds more: up to 3 for 30 seconds, 4 for 1 minute, 5 for 1.5 minutes and 6 for 2 minutes or more (a length between two of these counts as the longer one). Pick each character by its slug from ce_characters list: built-in ones and your own. Sending it replaces the whole cast. Default: the project's saved choice (leave it out).","minItems":1,"maxItems":6,"type":"array","items":{"type":"object","properties":{"character":{"description":"The character's slug from ce_characters list (or its exact name).","type":"string","minLength":1,"maxLength":120},"position":{"description":"Character position: Which corner a character stands in.\nChoices:\n- bottom-left — Bottom left: The character stands in the bottom left corner.\n- bottom-right — Bottom right: The character stands in the bottom right corner.\nDefault: Alternates, the first on the left (leave it out).","type":"string","enum":["bottom-left","bottom-right"]},"personality":{"description":"Character personality: The role a character plays in the conversation. Only one character is the lead (\"authority\"). When several would be, the first one you sent as \"authority\" keeps the role (if you sent none, the first one that is the lead by default), and the others become Skeptical Normies.\nChoices:\n- authority — Authority: The main character who sees the full picture, resolves tension.\n- naive-beginner — Naive Beginner: Asks basic questions everyone is thinking.\n- chaotic-zoomer — Chaotic Zoomer: Meme energy, half-informed but entertaining.\n- skeptical-normie — Skeptical Normie: Questions everything, healthy skepticism.\n- insider — Insider: Acts knowledgeable, implies hidden knowledge.\n- provocateur — Provocateur: Stirs controversy, pushes boundaries.\n- storyteller — Storyteller: Adds anecdotes, real-world examples.\n- comedian — Comedian: Turns everything into jokes, lightens mood.\n- philosopher — Philosopher: Goes deep, asks \"why\" behind everything.\n- hype-man — Hype Man: Gets excited, amplifies energy.\nDefault: The character's own default, else the lead (leave it out).","type":"string","enum":["authority","naive-beginner","chaotic-zoomer","skeptical-normie","insider","provocateur","storyteller","comedian","philosopher","hype-man"]}},"required":["character"],"additionalProperties":false}}},"additionalProperties":false},"example":{"style":"funny","durationSeconds":60}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"ce"},"title":{"type":"string"},"status":{"description":"Where the project is: draft, writing_script, script_ready, needs_speakers, waiting_for_approval, making, prepared_in_app, finished, no_video, failed, stalled.","type":"string","enum":["draft","writing_script","script_ready","needs_speakers","waiting_for_approval","making","prepared_in_app","finished","no_video","failed","stalled"]},"statusText":{"description":"The status in plain words.","type":"string"},"step":{"description":"What is being made right now, while status is making.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"type":"number"},"revision":{"description":"Send it back as expectedRevision when you change scenes.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"appLink":{"description":"Where to open the project in the app.","type":"string"},"autoPost":{"description":"Where a finished render posts itself.","type":"object","properties":{"platforms":{"type":"array","items":{"type":"string"}}},"required":["platforms"],"additionalProperties":{}},"nextStep":{"description":"What to do next, in plain words.","type":"string"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"settings":{"description":"The project's settings, in the same words create and update take.","type":"object","properties":{},"additionalProperties":{}},"characters":{"description":"The cast, lead first.","type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"position":{"description":"Which corner the character stands in.","type":"string"},"personality":{"description":"The role the character plays in the conversation.","anyOf":[{"type":"string"},{"type":"null"}]},"builtIn":{"type":"boolean"},"pictureUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slug","name","position","personality","builtIn","pictureUrl"],"additionalProperties":false}},"price":{"anyOf":[{"type":"object","properties":{"credits":{"description":"What rendering this video costs right now, in credits (nothing is charged until you render it with ce_render start).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"alreadyReserved":{"description":"Credits already set aside for this video (when it was prepared in the app, or by an earlier render of it that did not finish): only the difference is charged.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"balance":{"description":"Your credit balance now.","anyOf":[{"type":"number"},{"type":"null"}]},"notes":{"description":"How the price was worked out, in plain words.","type":"array","items":{"type":"string"}}},"required":["credits","alreadyReserved","balance","notes"],"additionalProperties":false},{"type":"null"}]}},"required":["id","product","title","status","statusText","step","progress","revision","appLink","autoPost","nextStep","createdAt","updatedAt","settings","characters","price"],"additionalProperties":{}},"notes":{"description":"What was changed from what you sent, and anything to know before the next step, in plain words.","type":"array","items":{"type":"string"}},"changed":{"description":"The settings this request set.","type":"array","items":{"type":"string"}}},"required":["project","notes","changed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","product":"ce","title":"How do black holes form?","status":"draft","statusText":"Draft. Next: write the script.","step":null,"progress":0,"revision":1791796320000,"appLink":"https://app.autoclips.app/character-explainer?sessionId=3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","autoPost":{"platforms":[]},"nextStep":"Write the script: ce_script generate.","createdAt":"2026-10-12T09:00:00.000Z","updatedAt":"2026-10-12T09:12:00.000Z","settings":{"inputMode":"topic","topic":"How do black holes form?","hasCustomScript":false,"style":"funny","durationSeconds":60,"language":"en","scriptMode":"normal","customInstructions":null,"ttsModel":"eleven_v4","voiceEmotion":"off","speechSpeed":1.15,"overrideSpeechSpeed":false,"visualMode":"gameplay","motionTheme":"cream","motionCaptionStyle":"classic","motionAuthorModel":"standard","intelligentVisualSourcing":true,"motionAssetModel":"grokImagine","motionAssetTier":"balanced","motionSoundDesign":"subtle","motionMusicMode":"auto","motionSfxMode":"auto","background":"minecraft_part_0","gameplayMediaId":null,"ownGameplay":false,"gameplaySpeed":"1","music":"none","musicLibraryTrack":null,"musicVolume":0.15,"showCaptions":true,"captionFont":"BebasNeue","captionSizeMultiplier":1,"captionVerticalPosition":44,"captionColor":"#FFFFFF","captionHighlightColor":"#FFD700","captionStrokeColor":"#000000","characterSizeMultiplier":1,"characterFloating":false,"floatingIntensity":50,"characterPlacementX":null,"characterPlacementY":null,"watermarkType":"none","watermarkText":null,"outroId":null},"characters":[{"slug":"peter-griffin","name":"Peter Griffin","position":"bottom-left","personality":"authority","builtIn":true,"pictureUrl":"https://media.autoclips.app/character-references/base-characters/peter-griffin.webp"}],"price":{"credits":50,"alreadyReserved":0,"balance":1200,"notes":[]}},"changed":["style","durationSeconds"],"notes":[]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"ce_projects_get","summary":"One Character Explainer project: where it is, and on request its settings, cast, script, price, video and post text.","description":"Opens one of your Character Explainer projects. Without include you get where it is (status in plain words, progress, what to do next), its revision, and a link to open it in the app. Add include for more: settings, characters, script, price, video, seo (for example include=script,price). Reading a project never changes it.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"ce.projects.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_projects action=get","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13"},{"name":"include","in":"query","required":false,"schema":{"description":"Extra sections. settings: the choices the video is made with. characters: the cast. script: every scene's words, and whether the script is longer than the length it is paid for. price: what starting the video costs now, for a draft or a failed video, with a note for each reason ce_render start would refuse it as it is now. video: the link and thumbnail once it is finished. seo: the title, description, tags and hashtags used when it is posted. Example: [\"script\", \"price\"].","maxItems":6,"type":"array","items":{"type":"string","enum":["settings","characters","script","price","video","seo"]}},"description":"Extra sections. settings: the choices the video is made with. characters: the cast. script: every scene's words, and whether the script is longer than the length it is paid for. price: what starting the video costs now, for a draft or a failed video, with a note for each reason ce_render start would refuse it as it is now. video: the link and thumbnail once it is finished. seo: the title, description, tags and hashtags used when it is posted. Example: [\"script\", \"price\"].","example":["video","seo"]}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"ce"},"title":{"type":"string"},"status":{"description":"Where the project is: draft, writing_script, script_ready, needs_speakers, waiting_for_approval, making, prepared_in_app, finished, no_video, failed, stalled.","type":"string","enum":["draft","writing_script","script_ready","needs_speakers","waiting_for_approval","making","prepared_in_app","finished","no_video","failed","stalled"]},"statusText":{"description":"The status in plain words.","type":"string"},"step":{"description":"What is being made right now, while status is making.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"type":"number"},"revision":{"description":"Send it back as expectedRevision when you change scenes.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"appLink":{"description":"Where to open the project in the app.","type":"string"},"autoPost":{"description":"Where a finished render posts itself.","type":"object","properties":{"platforms":{"type":"array","items":{"type":"string"}}},"required":["platforms"],"additionalProperties":{}},"nextStep":{"description":"What to do next, in plain words.","type":"string"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","product","title","status","statusText","step","progress","revision","appLink","autoPost","nextStep","createdAt","updatedAt"],"additionalProperties":{}}},"required":["project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"project":{"id":"7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13","product":"ce","title":"How black holes are born","status":"finished","statusText":"Finished.","step":null,"progress":100,"revision":1791620460000,"appLink":"https://app.autoclips.app/character-explainer?sessionId=7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13","autoPost":{"platforms":[]},"nextStep":"Watch it, post it (autoclips_publish) or read its versions (ce_render versions).","createdAt":"2026-10-10T08:00:00.000Z","updatedAt":"2026-10-10T08:21:00.000Z","video":{"url":"https://media.autoclips.app/videos/character-explainer/7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13.mp4","thumbnail":"https://media.autoclips.app/thumbnails/character-explainer/7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13.jpg","finishedAt":"2026-10-10T08:20:00.000Z"},"seo":{"title":"How black holes are born","description":"A star runs out of fuel, collapses, and a black hole is born. Peter explains it in 30 seconds.","tags":"black holes, space, astronomy, stars, physics, science","hashtags":"#space #blackhole #science #astronomy #learnontiktok"},"editedFrom":null}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"ce_projects_delete","summary":"Delete a Character Explainer project the way the app does. Not while it is being made.","description":"Deletes the project the way the app's Delete does: it is hidden from your library and from posting, and its video link keeps working. Edited versions the app's video editor saved are their own videos and are kept (ce_render versions lists them); its Director Console edits go with it. Deleting does not return credits set aside for the video (when it was prepared in the app, or by an earlier render of it that did not finish): render it instead to use them. The app's recovery check may still give back those of a render that stopped, deleted or not; the answer says when. A project that is being made, or that has a script, pictures or a motion graphics repair running, cannot be deleted until that finishes. AI apps ask the user first.\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["Character Explainer"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"ce.projects.delete","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_projects action=delete","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"5e9b1d7f-3c62-4a08-b4f1-8d2e6a0c7b94"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"projectId":{"type":"string"},"title":{"type":"string"},"keptEditedVersions":{"description":"How many edited versions the app's video editor saved of it (each its own project, finished or being made) were kept.","type":"integer","minimum":0,"maximum":9007199254740991},"directorConsoleEdits":{"description":"How many of its Director Console edits went with it (no longer listed; their links work until they expire).","type":"integer","minimum":0,"maximum":9007199254740991},"creditsSetAside":{"description":"Credits set aside for this video (when it was prepared in the app, or by an earlier render of it that did not finish), which deleting does not return (0 when there were none). The app's recovery check may still give back those of a render that stopped, deleted or not: note says when.","type":"integer","minimum":0,"maximum":9007199254740991},"note":{"description":"What deleting did, in plain words.","type":"string"}},"required":["deleted","projectId","title","keptEditedVersions","directorConsoleEdits","creditsSetAside","note"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"deleted":true,"projectId":"5e9b1d7f-3c62-4a08-b4f1-8d2e6a0c7b94","title":"Do octopuses dream?","keptEditedVersions":0,"directorConsoleEdits":0,"creditsSetAside":0,"note":"It is hidden from your library and from posting, and its video link keeps working."}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/projects/{projectId}/motion-repair":{"post":{"operationId":"ce_motion_repair","summary":"Repair the motion graphics of a motion graphics project, for example after its video failed on them. Free.","description":"Starts a repair of the motion graphics design of a motion graphics project: the scenes whose design did not pass its checks are designed again, and the scenes that passed are kept. Use it when a video failed on its motion graphics (the job error motion_repair_needed): the repair works from that failure, as saved on the project. Motion graphics are part of a paid plan, so a free plan gets plan_required. It is free on a paid plan, counts toward the daily limit of free AI helpers, and runs at most 5 times a day per project. Leave retry out to start a repair only when none is running and the failure was not repaired already (otherwise you get the state of the last repair and nothing new starts); send retry: true to start a fresh one even when one ran or is running. Not while something else is running on the project (for example the video being made, the script being written, or Quick Create waiting for your OK on its script), nor in the few minutes right after a render failed, while that render is still finishing. Follow it with repair_status; when the design is ready, make the video again with start.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"ce.motion.repair","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_render action=repair_motion","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"retry":{"description":"True starts a fresh repair even when one already ran or is running (each one counts toward the 5 a day). Leave it out to start one only when none is running.","type":"boolean"}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"description":"The project id.","type":"string"},"started":{"description":"True when this call started a new repair. False when one was already running, or the design needed none: the state is shown either way.","type":"boolean"},"repair":{"type":"object","properties":{"status":{"description":"idle (no repair has run), queued, classifying, repairing or verifying (a repair is running), ready (every scene passed its design checks) or failed (the repair stopped).","type":"string","enum":["idle","queued","classifying","repairing","verifying","ready","failed"]},"statusText":{"description":"The status in plain words.","type":"string"},"running":{"description":"True while a repair is waiting or working.","type":"boolean"},"designReady":{"description":"True when every scene passed its design checks, so the video can be rendered with ce_render start.","type":"boolean"},"progress":{"description":"Percent done of the repair (100 when ready).","type":"integer","minimum":0,"maximum":100},"completedScenes":{"description":"Scenes whose design passed its checks.","type":"integer","minimum":0,"maximum":9007199254740991},"totalScenes":{"description":"Scenes in the video.","type":"integer","minimum":0,"maximum":9007199254740991},"attempt":{"description":"Which attempt of this repair is running or ran last.","type":"integer","minimum":0,"maximum":9007199254740991},"maxAttempts":{"description":"How many attempts one repair makes before it stops.","type":"integer","minimum":0,"maximum":9007199254740991},"canRetry":{"description":"True when a stopped repair can be started again (repair_motion with retry: true).","type":"boolean"},"problem":{"description":"What went wrong, in plain words, while a repair runs or after it stopped.","anyOf":[{"type":"string"},{"type":"null"}]},"simplerDesign":{"description":"True when some scenes got a simpler design made on our side, because the full design could not be made for them.","type":"boolean"},"simplerScenes":{"description":"The scenes (numbered from 1) that got the simpler design.","type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"message":{"description":"What the repair is doing or did, in plain words.","type":"string"},"updatedAt":{"description":"When the repair last changed.","anyOf":[{"type":"string"},{"type":"null"}]},"nextStep":{"description":"What to do next, in plain words.","type":"string"}},"required":["status","statusText","running","designReady","progress","completedScenes","totalScenes","attempt","maxAttempts","canRetry","problem","simplerDesign","simplerScenes","message","updatedAt","nextStep"],"additionalProperties":false}},"required":["projectId","started","repair"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","started":true,"repair":{"status":"queued","statusText":"A repair is waiting to start.","running":true,"designReady":false,"progress":0,"completedScenes":0,"totalScenes":3,"attempt":0,"maxAttempts":3,"canRetry":false,"problem":"Some scenes did not pass their design checks.","simplerDesign":false,"simplerScenes":[],"message":"A safe repair is queued. Your completed scenes will be kept.","updatedAt":"2026-10-12T09:20:00.000Z","nextStep":"Wait a minute, then check again with ce_render repair_status."}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"ce_motion_get_repair","summary":"How the motion graphics repair of a project is going, and whether its design is ready to render. Free.","description":"Reads the state of the motion graphics design of a motion graphics project: whether a repair is running and how far it is, whether it stopped, and whether every scene passed its design checks (designReady), so the video can be made with start. A repair that stopped answering is picked up again when you read it.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"ce.motion.get_repair","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_render action=repair_status","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"description":"The project id.","type":"string"},"repair":{"type":"object","properties":{"status":{"description":"idle (no repair has run), queued, classifying, repairing or verifying (a repair is running), ready (every scene passed its design checks) or failed (the repair stopped).","type":"string","enum":["idle","queued","classifying","repairing","verifying","ready","failed"]},"statusText":{"description":"The status in plain words.","type":"string"},"running":{"description":"True while a repair is waiting or working.","type":"boolean"},"designReady":{"description":"True when every scene passed its design checks, so the video can be rendered with ce_render start.","type":"boolean"},"progress":{"description":"Percent done of the repair (100 when ready).","type":"integer","minimum":0,"maximum":100},"completedScenes":{"description":"Scenes whose design passed its checks.","type":"integer","minimum":0,"maximum":9007199254740991},"totalScenes":{"description":"Scenes in the video.","type":"integer","minimum":0,"maximum":9007199254740991},"attempt":{"description":"Which attempt of this repair is running or ran last.","type":"integer","minimum":0,"maximum":9007199254740991},"maxAttempts":{"description":"How many attempts one repair makes before it stops.","type":"integer","minimum":0,"maximum":9007199254740991},"canRetry":{"description":"True when a stopped repair can be started again (repair_motion with retry: true).","type":"boolean"},"problem":{"description":"What went wrong, in plain words, while a repair runs or after it stopped.","anyOf":[{"type":"string"},{"type":"null"}]},"simplerDesign":{"description":"True when some scenes got a simpler design made on our side, because the full design could not be made for them.","type":"boolean"},"simplerScenes":{"description":"The scenes (numbered from 1) that got the simpler design.","type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"message":{"description":"What the repair is doing or did, in plain words.","type":"string"},"updatedAt":{"description":"When the repair last changed.","anyOf":[{"type":"string"},{"type":"null"}]},"nextStep":{"description":"What to do next, in plain words.","type":"string"}},"required":["status","statusText","running","designReady","progress","completedScenes","totalScenes","attempt","maxAttempts","canRetry","problem","simplerDesign","simplerScenes","message","updatedAt","nextStep"],"additionalProperties":false}},"required":["projectId","repair"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"projectId":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","repair":{"status":"repairing","statusText":"Repairing the scenes.","running":true,"designReady":false,"progress":40,"completedScenes":0,"totalScenes":3,"attempt":1,"maxAttempts":3,"canRetry":false,"problem":"Some scenes did not pass their design checks.","simplerDesign":false,"simplerScenes":[],"message":"Repairing only the scenes that did not pass visual checks.","updatedAt":"2026-10-12T09:22:00.000Z","nextStep":"Wait a minute, then check again with ce_render repair_status."}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/projects/{projectId}/pictures":{"post":{"operationId":"ce_pictures_generate","summary":"Make an AI picture for each chosen scene and put it on the scene. Costs credits; answers with a job.","description":"An AI draws one picture per scene, from your prompt or the scene's picture idea in the script, and the picture goes on its scene (and into your media library). Each picture costs the model's price (9 models; the model field lists the usual price, and the quote shows the price on your plan), charged when it is made; a picture that fails is given back. Before each picture the run checks the price again, and starts the picture only if the run stays within the price you approved. If your picture price changes while the pictures are being made (for example because your plan changed), a picture already being made is charged the new price, and any amount that takes the run past the price you approved is given back, so the run never costs more than approved. Paid plans only. Gameplay videos only (motion graphics videos make their own pictures). The project must be a draft with a script, and nothing else may be running on it. At most 50 pictures per run, 3 at a time. It runs in the background: follow the job. A scene that changes while its picture is made keeps what it shows, and the new picture stays in your media library (the job lists it).\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Character Explainer"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"ce.pictures.generate","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"ce_scenes action=generate_pictures","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"description":"Picture maker: Which model draws a scene picture. Each picture is charged when it is made; a picture that fails is given back.\nChoices:\n- ideogram2a — Ideogram 2.0a: Best quality, great for any content. (16 credits per picture; plans: paid)\n- recraftV3 — Recraft V3: High quality, versatile styles. (16 credits per picture; plans: paid)\n- zImageTurbo — Z-Image Turbo: Fast and inexpensive. (5 credits per picture; plans: paid)\n- fluxSchnell — Flux 2 Turbo: Excellent quality, fast. (12 credits per picture; plans: paid)\n- fluxDev — Flux Dev: Good quality. (12 credits per picture; plans: paid)\n- fluxPro — Flux 2 Pro: Premium quality. (16 credits per picture; plans: paid)\n- krea2Medium — Krea 2: Stunning aesthetics, rich artistic styles. (20 credits per picture; plans: paid)\n- nanoBanana2 — Nano Banana 2: Sharpest detail, best at following the prompt. (48 credits per picture; plans: paid)\n- grokImagine — Grok Imagine: Photoreal, relaxed about public figures. (10 credits per picture; plans: paid)\nNo default: ask the user.","type":"string","enum":["ideogram2a","recraftV3","zImageTurbo","fluxSchnell","fluxDev","fluxPro","krea2Medium","nanoBanana2","grokImagine"]},"scenes":{"description":"Which scenes get a picture: \"without_picture\" (the default): every scene that shows no picture yet; \"all\": every scene, replacing the pictures they show; or a list of up to 50 scenes by number, each with your own prompt if you like (without one, the scene's picture idea from the script is used). Scenes with no picture idea are left out of \"all\" and \"without_picture\" (the answer lists them).","anyOf":[{"type":"string","enum":["without_picture","all"]},{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"sceneNumber":{"description":"The scene number: 1 for the first scene (ce_scenes list shows them).","type":"integer","minimum":1,"maximum":500},"prompt":{"description":"What the picture shows, in your own words (3 to 1500 characters). Leave it out to use the scene's picture idea from the script.","type":"string","minLength":3,"maxLength":1500}},"required":["sceneNumber"],"additionalProperties":false}}]},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"required":["model"],"additionalProperties":false},"example":{"model":"zImageTurbo"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"description":"The project the pictures are for.","type":"string"},"job":{"description":"Follow it with autoclips_jobs get (or GET /v1/jobs/{id}). Its result lists each picture: placed (on its scene), in_library (made and in your media library, but not put on its scene; its why says why), failed or not_made, with what each was charged. A picture a price change charged past the price you approved also says what was given back (creditsGivenBack).","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"model":{"description":"The picture model.","type":"string"},"creditsPerPicture":{"description":"What one picture costs on your plan. A picture that fails is given back.","type":"integer","minimum":0,"maximum":9007199254740991},"pictures":{"description":"The scenes a picture is being made for.","type":"array","items":{"type":"object","properties":{"sceneNumber":{"description":"The scene, by number (1 for the first).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"promptFrom":{"description":"yours: the prompt you sent; picture_idea: the scene's picture idea from the script.","type":"string","enum":["yours","picture_idea"]}},"required":["sceneNumber","promptFrom"],"additionalProperties":false}},"skipped":{"description":"Scenes left out, and why.","type":"array","items":{"type":"object","properties":{"sceneNumber":{"description":"The scene left out, by number.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reason":{"description":"Why, as a code: no_picture_idea (the script gives the scene no picture idea).","type":"string"},"why":{"description":"The reason in plain words.","type":"string"}},"required":["sceneNumber","reason","why"],"additionalProperties":false}},"alreadyStarted":{"description":"True when an earlier try of this same request already started these pictures: you get its job back, and nothing new is charged.","type":"boolean"}},"required":["projectId","job","model","creditsPerPicture","pictures","skipped","alreadyStarted"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","job":{"id":"job_0199d81a2b3c4d5e6f708192","product":"ce","kind":"ce.pictures","resource":{"type":"project","id":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22"},"status":"running","step":"Making scene pictures: 0 of 3 done","progress":0,"result":null,"error":null,"createdAt":"2026-10-12T10:00:00.000Z","updatedAt":"2026-10-12T10:00:00.000Z","finishedAt":null,"poll_after_seconds":15,"usualSeconds":30},"model":"zImageTurbo","creditsPerPicture":5,"pictures":[{"sceneNumber":1,"promptFrom":"picture_idea"},{"sceneNumber":3,"promptFrom":"picture_idea"},{"sceneNumber":4,"promptFrom":"picture_idea"}],"skipped":[],"alreadyStarted":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/projects/{projectId}/render":{"post":{"operationId":"ce_render_start","summary":"Make the video from a project whose script is ready. Paid; answers with a job.","description":"Makes the video file from a Character Explainer project whose script is written: the voices, the motion graphics (for a motion graphics project) and the render, from the settings and script saved on the project. It costs credits: the price for the project's length and script quality (a pasted script longer than the length is billed for its own length; free plans make 30-second videos), plus motion graphics when the project uses them, and on your plan's price. When credits were already set aside for this video (it was prepared for the timeline editor in the app, or an earlier render of it did not finish and its credits did not come back), only the difference is charged. If the price is higher by the time it starts, nothing is charged and the answer is 409 price_changed with the new price: ask for a new price. Only a draft or a failed project can start, and only one that is not busy with anything else. A video whose work stopped while it was being made (nothing changed on it for 25 minutes, the app's own rule for a stopped render) counts as stopped: its job fails with code stalled, and it can start again. Right after a render fails, wait a few minutes before starting it again: that render may still try again by itself and its credits are being settled (409 render_finishing until then). The script (with two or more characters, the lines they speak) may be at most a quarter longer than what the paid length is written for; a longer one is refused with its length and the price at a length it fits (change the length with ce_projects update, or shorten the script with ce_scenes update). Every scene must be said by a character in the video: scenes still said by characters who left it (the cast was changed in the app after the script was written) are named in a refusal, with the two ways to set them. Your plan's daily video limit applies. Free plans make 30-second videos, paid for from the 150 credits a new account gets, and every free video carries a small \"Made with Autoclips.app\" badge. A finished video cannot be made again through the API yet: to make a new version of it, open it in the app (its appLink) and use Re-render Video there (your current video stays until the new one is ready), or make a new project (ce_projects create). If the project posts itself to social accounts when it is finished, the key needs the publish permission, and the preview names the accounts. It answers with a job right away (status 202); follow it with autoclips_jobs get. A started video cannot be stopped. If making it fails, its credits are usually given back by themselves; credits still set aside are used again by the next start, so it never pays for the same video twice. A failed job says why (result.cause) and what to do; if it failed on its motion graphics, repair them with repair_motion, then start again.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Character Explainer"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"ce.render.start","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"ce_render action=start","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job":{"description":"Follow it with autoclips_jobs get. When it succeeds, result.videoUrl is the video. If it fails on its motion graphics, its error code is motion_repair_needed.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"project":{"description":"The project right after the start, in the same shape as ce_projects get.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"ce"},"title":{"type":"string"},"status":{"description":"Where the project is: draft, writing_script, script_ready, needs_speakers, waiting_for_approval, making, prepared_in_app, finished, no_video, failed, stalled.","type":"string","enum":["draft","writing_script","script_ready","needs_speakers","waiting_for_approval","making","prepared_in_app","finished","no_video","failed","stalled"]},"statusText":{"description":"The status in plain words.","type":"string"},"step":{"description":"What is being made right now, while status is making.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"type":"number"},"revision":{"description":"Send it back as expectedRevision when you change scenes.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"appLink":{"description":"Where to open the project in the app.","type":"string"},"autoPost":{"description":"Where a finished render posts itself.","type":"object","properties":{"platforms":{"type":"array","items":{"type":"string"}}},"required":["platforms"],"additionalProperties":{}},"nextStep":{"description":"What to do next, in plain words.","type":"string"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","product","title","status","statusText","step","progress","revision","appLink","autoPost","nextStep","createdAt","updatedAt"],"additionalProperties":{}},"creditsCharged":{"description":"Credits this start charged: the video price, or only the difference when credits were already set aside for this video (when it was prepared in the app, or by an earlier render of it that did not finish).","type":"integer","minimum":0,"maximum":9007199254740991},"autoPost":{"description":"Social platforms the finished video is posted to by itself, from the project's publishing settings. Empty when nothing is posted.","type":"array","items":{"type":"string","enum":["tiktok","youtube","instagram","facebook","twitter","snapchat"]}},"notes":{"description":"Things to know about a started video, in plain words.","type":"array","items":{"type":"string"}}},"required":["job","project","creditsCharged","autoPost","notes"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"job":{"id":"job_0199d7a3f2c0a1b2c3d4e5f6","product":"ce","kind":"ce.render","resource":{"type":"project","id":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22"},"status":"running","step":"Starting","progress":0,"result":null,"error":null,"createdAt":"2026-10-12T09:06:00.000Z","updatedAt":"2026-10-12T09:06:00.000Z","finishedAt":null,"poll_after_seconds":10,"usualSeconds":240},"project":{"id":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","product":"ce","title":"How do black holes form?","status":"making","statusText":"Being made: Generating voice (30%).","step":"Generating voice","progress":30,"revision":1791795960000,"appLink":"https://app.autoclips.app/character-explainer?sessionId=3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","autoPost":{"platforms":[]},"nextStep":"Wait for the video: follow its job with autoclips_jobs, or read the project again.","createdAt":"2026-10-12T09:00:00.000Z","updatedAt":"2026-10-12T09:06:00.000Z"},"creditsCharged":50,"autoPost":[],"notes":["A started video cannot be stopped.","If making it fails, its credits are usually given back by themselves within minutes. Credits that have not come back (for example when the work making it stopped) are used again by the next ce_render start, so starting it again never pays for this video twice."]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/projects/{projectId}/scenes":{"get":{"operationId":"ce_scenes_list","summary":"Every scene of a Character Explainer project: words, speaker, picture, sound effect, plus the revision to change them.","description":"Lists the scenes in order, numbered from 1: who says what, the picture idea, the picture (or pictures) and sound effect on the scene, its timing once voiced, and whether its words were changed after the script was written. Also the project revision (send it as expectedRevision when you change a scene), whether the scenes can be changed now, the characters who can speak, and how long the script runs against the length it is paid for. Free.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"ce.scenes.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_scenes action=list","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"revision":{"description":"The project revision now: send it as expectedRevision with your next change.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"description":"Where the project is (ce_projects get explains each status).","type":"string"},"canEdit":{"description":"Whether the scenes can be changed right now.","type":"boolean"},"notEditableBecause":{"description":"Why not, in plain words, when canEdit is false.","anyOf":[{"type":"string"},{"type":"null"}]},"picturesAndSoundEffects":{"description":"Whether scene pictures and sound effects can be changed here. False for a motion graphics video: the render makes its own slides, so scene pictures are not used, and its sound effects follow its Motion sound effects setting (motionSfxMode; a pick per scene, \"library\", is made in the app).","type":"boolean"},"speakers":{"description":"The characters who can say a scene (update speaker). A script written for one character on a video that now has more lists only the first: that character voices every scene until the script is written again for the whole cast (ce_script generate with replace: true).","type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}},"required":["name","slug"],"additionalProperties":false}},"length":{"type":"object","properties":{"unit":{"description":"word, or character for Japanese, Chinese and Thai.","type":"string","enum":["word","character"]},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"estimatedSeconds":{"description":"About how long the script runs when spoken.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"paidSeconds":{"description":"The length the video is paid for.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"longerThanPaid":{"description":"True when the script is too long for that length: ce_render start refuses it until the script is shorter or, on a paid plan, the video is made longer (ce_projects update). The notes say which, for your plan.","type":"boolean"}},"required":["unit","count","estimatedSeconds","paidSeconds","longerThanPaid"],"additionalProperties":false},"scenes":{"type":"array","items":{"type":"object","properties":{"number":{"description":"The scene number, from 1.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"speaker":{"description":"Who says it.","anyOf":[{"type":"string"},{"type":"null"}]},"words":{"description":"What is said.","type":"string"},"pictureIdea":{"description":"What the scene's picture should show (the AI picture prompt).","anyOf":[{"type":"string"},{"type":"null"}]},"hasPicture":{"type":"boolean"},"soundEffect":{"anyOf":[{"description":"A sound effect played when the scene starts.","type":"object","properties":{"id":{"description":"The effect id (the catalog option soundEffect).","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"description":"Its kind: impacts, whooshes, pop, …","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","description","category"],"additionalProperties":false},{"type":"null"}]},"needsNewVoice":{"description":"True when its words were changed after the script was written (here or in the app). The next render voices the words as they are now.","type":"boolean"},"picture":{"anyOf":[{"type":"object","properties":{"url":{"description":"The picture shown first.","type":"string"},"type":{"type":"string","enum":["image","video"]},"mediaId":{"description":"Its id in your media library, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"items":{"description":"How many pictures the scene shows one after the other.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["url","type","mediaId","items"],"additionalProperties":false},{"type":"null"}]},"timing":{"description":"When the scene plays, once its voice is recorded.","anyOf":[{"type":"object","properties":{"startSeconds":{"type":"number"},"endSeconds":{"type":"number"}},"required":["startSeconds","endSeconds"],"additionalProperties":false},{"type":"null"}]}},"required":["number","speaker","words","pictureIdea","hasPicture","soundEffect","needsNewVoice","picture","timing"],"additionalProperties":false}},"nextStep":{"type":"string"}},"required":["projectId","revision","status","canEdit","notEditableBecause","picturesAndSoundEffects","speakers","length","scenes","nextStep"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"projectId":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","revision":1791796800000,"status":"script_ready","canEdit":true,"notEditableBecause":null,"picturesAndSoundEffects":true,"speakers":[{"name":"Peter Griffin","slug":"peter-griffin"},{"name":"Stewie Griffin","slug":"stewie-griffin"}],"length":{"unit":"word","count":28,"estimatedSeconds":11,"paidSeconds":30,"longerThanPaid":false},"scenes":[{"number":1,"speaker":"Peter Griffin","words":"Black holes are what happens when a giant star runs out of fuel.","pictureIdea":"A giant star collapsing in space","hasPicture":true,"soundEffect":{"id":"braam-1","description":"Fat distorted cinematic braam, ominous and powerful like Inception","category":"impacts"},"needsNewVoice":false,"picture":{"url":"https://media.autoclips.app/clips/character-explainer/user_123/api/7d1f0c3e.jpg","type":"image","mediaId":"66f7c0ffee00000000000001","items":1},"timing":null},{"number":2,"speaker":"Stewie Griffin","words":"So the star just falls into itself?","pictureIdea":"A star shrinking to a tiny point","hasPicture":false,"soundEffect":null,"needsNewVoice":false,"picture":null,"timing":null},{"number":3,"speaker":"Peter Griffin","words":"Exactly, and nothing gets out, not even light.","pictureIdea":"Light bending around a black hole","hasPicture":true,"soundEffect":null,"needsNewVoice":false,"picture":{"url":"https://media.autoclips.app/character-explainer/scene-images/3f1c2b7e/scene-3a.jpg","type":"image","mediaId":null,"items":2},"timing":null}],"nextStep":"Check the scenes (ce_scenes list), add pictures if you like (ce_scenes generate_pictures), then render (ce_render start)."}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/projects/{projectId}/scenes/{sceneNumber}":{"patch":{"operationId":"ce_scenes_update","summary":"Change one scene's words, who says them, or its picture idea. Free.","description":"Changes what a character says in a scene, which of the project's characters says it, or the scene's picture idea (send any of words, speaker, pictureIdea). New words are voiced at the next render. The answer gives the previous values (send them back to undo) and the new revision. A script written for one character on a video that now has more is voiced by the first character throughout, so another speaker is refused there until the script is written again for the whole cast. Only while the project is a draft; expectedRevision is required. Free.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"ce.scenes.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_scenes action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedRevision":{"description":"The project revision you last read (ce_projects get or ce_scenes list). If the project changed since, nothing is saved and you are told to read it again.","type":"integer","minimum":0,"maximum":9007199254740991},"words":{"description":"What the character says in this scene, at most 2000 characters. Spoken at the next render. Example: \"Wait, so the star just falls into itself?\"","type":"string","minLength":1,"maxLength":2000},"speaker":{"description":"Who says it: one of the project's characters, by slug or name (ce_scenes list shows them as speakers). Example: stewie-griffin.","type":"string","minLength":1,"maxLength":120},"pictureIdea":{"description":"What the scene's picture should show, at most 500 characters. generate_pictures draws it from this. Example: \"A star shrinking to a tiny bright point\".","type":"string","minLength":1,"maxLength":500}},"required":["expectedRevision"],"additionalProperties":false},"example":{"expectedRevision":1791796800000,"words":"Wait, so the star just falls into itself?"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22"},{"name":"sceneNumber","in":"path","required":true,"schema":{"description":"The scene number: 1 for the first scene (ce_scenes list shows them).","type":"integer","minimum":1,"maximum":500},"description":"The scene number: 1 for the first scene (ce_scenes list shows them).","example":2},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"revision":{"description":"The project revision now: send it as expectedRevision with your next change.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"scene":{"type":"object","properties":{"number":{"description":"The scene number, from 1.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"speaker":{"description":"Who says it.","anyOf":[{"type":"string"},{"type":"null"}]},"words":{"description":"What is said.","type":"string"},"pictureIdea":{"description":"What the scene's picture should show (the AI picture prompt).","anyOf":[{"type":"string"},{"type":"null"}]},"hasPicture":{"type":"boolean"},"soundEffect":{"anyOf":[{"description":"A sound effect played when the scene starts.","type":"object","properties":{"id":{"description":"The effect id (the catalog option soundEffect).","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"description":"Its kind: impacts, whooshes, pop, …","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","description","category"],"additionalProperties":false},{"type":"null"}]},"needsNewVoice":{"description":"True when its words were changed after the script was written (here or in the app). The next render voices the words as they are now.","type":"boolean"},"picture":{"anyOf":[{"type":"object","properties":{"url":{"description":"The picture shown first.","type":"string"},"type":{"type":"string","enum":["image","video"]},"mediaId":{"description":"Its id in your media library, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"items":{"description":"How many pictures the scene shows one after the other.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["url","type","mediaId","items"],"additionalProperties":false},{"type":"null"}]},"timing":{"description":"When the scene plays, once its voice is recorded.","anyOf":[{"type":"object","properties":{"startSeconds":{"type":"number"},"endSeconds":{"type":"number"}},"required":["startSeconds","endSeconds"],"additionalProperties":false},{"type":"null"}]}},"required":["number","speaker","words","pictureIdea","hasPicture","soundEffect","needsNewVoice","picture","timing"],"additionalProperties":false},"changed":{"description":"What changed (empty when everything already was as sent).","type":"array","items":{"type":"string","enum":["words","speaker","pictureIdea"]}},"previous":{"description":"The scene before the change: send these back with update to undo it.","type":"object","properties":{"words":{"type":"string"},"speaker":{"anyOf":[{"type":"string"},{"type":"null"}]},"pictureIdea":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["words","speaker","pictureIdea"],"additionalProperties":false},"length":{"type":"object","properties":{"unit":{"description":"word, or character for Japanese, Chinese and Thai.","type":"string","enum":["word","character"]},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"estimatedSeconds":{"description":"About how long the script runs when spoken.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"paidSeconds":{"description":"The length the video is paid for.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"longerThanPaid":{"description":"True when the script is too long for that length: ce_render start refuses it until the script is shorter or, on a paid plan, the video is made longer (ce_projects update). The notes say which, for your plan.","type":"boolean"}},"required":["unit","count","estimatedSeconds","paidSeconds","longerThanPaid"],"additionalProperties":false},"notes":{"type":"array","items":{"type":"string"}}},"required":["projectId","revision","scene","changed","previous","length","notes"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","revision":1791796890000,"scene":{"number":2,"speaker":"Stewie Griffin","words":"Wait, so the star just falls into itself?","pictureIdea":"A star shrinking to a tiny point","hasPicture":false,"soundEffect":null,"needsNewVoice":true,"picture":null,"timing":null},"changed":["words"],"previous":{"words":"So the star just falls into itself?","speaker":"Stewie Griffin","pictureIdea":"A star shrinking to a tiny point"},"length":{"unit":"word","count":29,"estimatedSeconds":11,"paidSeconds":30,"longerThanPaid":false},"notes":["The new words are voiced when the video is made (ce_render start)."]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/projects/{projectId}/scenes/{sceneNumber}/picture":{"put":{"operationId":"ce_scenes_set_picture","summary":"Put one of your own pictures or videos (from your media library) on a scene. Free.","description":"Puts a picture or video from your media library on a scene, replacing the one there. Upload it first with autoclips_media. A scene that shows several pictures one after the other takes `item` (from 1; default the first), keeping its timing. Gameplay videos only (motion graphics videos make their own slides). Only while the project is a draft; expectedRevision is required. The answer names the picture it replaced; when that picture is in your media library, set_picture with its mediaId puts it back. Free.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"ce.scenes.set_picture","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_scenes action=set_picture","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedRevision":{"description":"The project revision you last read (ce_projects get or ce_scenes list). If the project changed since, nothing is saved and you are told to read it again.","type":"integer","minimum":0,"maximum":9007199254740991},"mediaId":{"description":"A picture or video from your media library (autoclips_media list, upload_link or import_url). Example: 66f7c0ffee00000000000002.","type":"string","pattern":"^[a-fA-F0-9]{24}$"},"item":{"description":"Which of the scene's pictures, from 1, when it shows several one after the other (ce_scenes list: picture.items). set_picture: default 1, the first. remove_picture: default every picture of the scene. Example: 2.","type":"integer","minimum":1,"maximum":50}},"required":["expectedRevision","mediaId"],"additionalProperties":false},"example":{"expectedRevision":1791796800000,"mediaId":"66f7c0ffee00000000000002"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22"},{"name":"sceneNumber","in":"path","required":true,"schema":{"description":"The scene number: 1 for the first scene (ce_scenes list shows them).","type":"integer","minimum":1,"maximum":500},"description":"The scene number: 1 for the first scene (ce_scenes list shows them).","example":2},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"revision":{"description":"The project revision now: send it as expectedRevision with your next change.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sceneNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"item":{"description":"Which of the scene's pictures changed, from 1.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pictures":{"description":"How many pictures the scene shows one after the other.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"placed":{"description":"The picture now there.","type":"object","properties":{"url":{"type":"string"},"type":{"type":"string","enum":["image","video"]},"mediaId":{"description":"Its id in your media library, when it is there: give it to set_picture to put it back.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","type","mediaId"],"additionalProperties":false},"previous":{"description":"The picture it replaced (null when there was none). To undo, call set_picture with previous.mediaId; when it is null, that picture is not in your media library and cannot be put back.","anyOf":[{"type":"object","properties":{"url":{"type":"string"},"type":{"type":"string","enum":["image","video"]},"mediaId":{"description":"Its id in your media library, when it is there: give it to set_picture to put it back.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","type","mediaId"],"additionalProperties":false},{"type":"null"}]},"scene":{"type":"object","properties":{"number":{"description":"The scene number, from 1.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"speaker":{"description":"Who says it.","anyOf":[{"type":"string"},{"type":"null"}]},"words":{"description":"What is said.","type":"string"},"pictureIdea":{"description":"What the scene's picture should show (the AI picture prompt).","anyOf":[{"type":"string"},{"type":"null"}]},"hasPicture":{"type":"boolean"},"soundEffect":{"anyOf":[{"description":"A sound effect played when the scene starts.","type":"object","properties":{"id":{"description":"The effect id (the catalog option soundEffect).","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"description":"Its kind: impacts, whooshes, pop, …","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","description","category"],"additionalProperties":false},{"type":"null"}]},"needsNewVoice":{"description":"True when its words were changed after the script was written (here or in the app). The next render voices the words as they are now.","type":"boolean"},"picture":{"anyOf":[{"type":"object","properties":{"url":{"description":"The picture shown first.","type":"string"},"type":{"type":"string","enum":["image","video"]},"mediaId":{"description":"Its id in your media library, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"items":{"description":"How many pictures the scene shows one after the other.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["url","type","mediaId","items"],"additionalProperties":false},{"type":"null"}]},"timing":{"description":"When the scene plays, once its voice is recorded.","anyOf":[{"type":"object","properties":{"startSeconds":{"type":"number"},"endSeconds":{"type":"number"}},"required":["startSeconds","endSeconds"],"additionalProperties":false},{"type":"null"}]}},"required":["number","speaker","words","pictureIdea","hasPicture","soundEffect","needsNewVoice","picture","timing"],"additionalProperties":false},"notes":{"description":"Anything to know about the change, such as a replaced picture that cannot be put back.","type":"array","items":{"type":"string"}}},"required":["projectId","revision","sceneNumber","item","pictures","placed","previous","scene","notes"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","revision":1791796890000,"sceneNumber":2,"item":1,"pictures":1,"placed":{"url":"https://media.autoclips.app/clips/character-explainer/user_123/api/a9b8c7d6.jpg","type":"image","mediaId":"66f7c0ffee00000000000002"},"previous":null,"scene":{"number":2,"speaker":"Stewie Griffin","words":"So the star just falls into itself?","pictureIdea":"A star shrinking to a tiny point","hasPicture":true,"soundEffect":null,"needsNewVoice":false,"picture":{"url":"https://media.autoclips.app/clips/character-explainer/user_123/api/a9b8c7d6.jpg","type":"image","mediaId":"66f7c0ffee00000000000002","items":1},"timing":null},"notes":[]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"ce_scenes_remove_picture","summary":"Take the picture off a scene. No file is deleted. Free.","description":"Takes a scene's picture (or, with `item`, one of its pictures) off the scene. A scene with no picture of its own does not show the gameplay by itself: in the video, the picture of the nearest scene before it that has one stays on screen until the next picture appears (the gameplay shows where no scene before it has a picture); the answer says which. No file is deleted: the answer names what was removed, and when a picture is in your media library, set_picture with its mediaId puts it back. Gameplay videos only. Only while the project is a draft; expectedRevision is required. Free.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"ce.scenes.remove_picture","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_scenes action=remove_picture","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedRevision":{"description":"The project revision you last read (ce_projects get or ce_scenes list). If the project changed since, nothing is saved and you are told to read it again.","type":"integer","minimum":0,"maximum":9007199254740991},"item":{"description":"Which of the scene's pictures, from 1, when it shows several one after the other (ce_scenes list: picture.items). set_picture: default 1, the first. remove_picture: default every picture of the scene. Example: 2.","type":"integer","minimum":1,"maximum":50}},"required":["expectedRevision"],"additionalProperties":false},"example":{"expectedRevision":1791796800000}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22"},{"name":"sceneNumber","in":"path","required":true,"schema":{"description":"The scene number: 1 for the first scene (ce_scenes list shows them).","type":"integer","minimum":1,"maximum":500},"description":"The scene number: 1 for the first scene (ce_scenes list shows them).","example":1},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"revision":{"description":"The project revision now: send it as expectedRevision with your next change.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sceneNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"removed":{"description":"What was taken off (empty when the scene had no picture). To undo, call set_picture with a mediaId from here; a picture whose mediaId is null is not in your media library and cannot be put back.","type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"type":{"type":"string","enum":["image","video"]},"mediaId":{"description":"Its id in your media library, when it is there: give it to set_picture to put it back.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","type","mediaId"],"additionalProperties":false}},"scene":{"type":"object","properties":{"number":{"description":"The scene number, from 1.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"speaker":{"description":"Who says it.","anyOf":[{"type":"string"},{"type":"null"}]},"words":{"description":"What is said.","type":"string"},"pictureIdea":{"description":"What the scene's picture should show (the AI picture prompt).","anyOf":[{"type":"string"},{"type":"null"}]},"hasPicture":{"type":"boolean"},"soundEffect":{"anyOf":[{"description":"A sound effect played when the scene starts.","type":"object","properties":{"id":{"description":"The effect id (the catalog option soundEffect).","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"description":"Its kind: impacts, whooshes, pop, …","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","description","category"],"additionalProperties":false},{"type":"null"}]},"needsNewVoice":{"description":"True when its words were changed after the script was written (here or in the app). The next render voices the words as they are now.","type":"boolean"},"picture":{"anyOf":[{"type":"object","properties":{"url":{"description":"The picture shown first.","type":"string"},"type":{"type":"string","enum":["image","video"]},"mediaId":{"description":"Its id in your media library, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"items":{"description":"How many pictures the scene shows one after the other.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["url","type","mediaId","items"],"additionalProperties":false},{"type":"null"}]},"timing":{"description":"When the scene plays, once its voice is recorded.","anyOf":[{"type":"object","properties":{"startSeconds":{"type":"number"},"endSeconds":{"type":"number"}},"required":["startSeconds","endSeconds"],"additionalProperties":false},{"type":"null"}]}},"required":["number","speaker","words","pictureIdea","hasPicture","soundEffect","needsNewVoice","picture","timing"],"additionalProperties":false},"notes":{"description":"Whether what was removed can be put back, and what the video shows on the scene now.","type":"array","items":{"type":"string"}}},"required":["projectId","revision","sceneNumber","removed","scene","notes"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","revision":1791796890000,"sceneNumber":1,"removed":[{"url":"https://media.autoclips.app/clips/character-explainer/user_123/api/7d1f0c3e.jpg","type":"image","mediaId":"66f7c0ffee00000000000001"}],"scene":{"number":1,"speaker":"Peter Griffin","words":"Black holes are what happens when a giant star runs out of fuel.","pictureIdea":"A giant star collapsing in space","hasPicture":false,"soundEffect":{"id":"braam-1","description":"Fat distorted cinematic braam, ominous and powerful like Inception","category":"impacts"},"needsNewVoice":false,"picture":null,"timing":null},"notes":["No file was deleted: it stays in your media library.","Scene 1 now has no picture of its own, and no scene before it has one, so the gameplay shows there until the next picture appears."]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/projects/{projectId}/scenes/{sceneNumber}/rewrite":{"post":{"operationId":"ce_scenes_rewrite","summary":"Two AI rewrites of one scene's words, in context. Nothing is saved: update saves the one you pick.","description":"An AI rewrites what a character says in one scene, with the whole script as context, following a preset (funnier, shorter, …) and/or your own instructions, and answers with two versions. Nothing is saved: save the one the user picks with update (words). Works on a draft or a failed video; update saves only on a draft, so a failed video goes back to one with ce_projects update first. Free, within the daily limit for free AI helpers.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"ce.scenes.rewrite","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_scenes action=rewrite","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"preset":{"description":"Rewrite: How to rewrite one scene's words. You get two versions to choose from; nothing is saved until you pick one. Free.\nChoices:\n- funnier — Make it funnier: Add humor, wit or a comedic twist.\n- educational — More educational: Add a useful fact, tip or insight while keeping it engaging.\n- urgent — Add urgency: More energy and excitement, so viewers feel they must pay attention.\n- professional — More professional: More credible and polished, still conversational.\n- plug — Better product plug: Promote the product or topic naturally, with a specific benefit.\n- shorter — Make it shorter: Shorter and punchier: the same message in fewer words.\n- longer — Make it longer: More detail, an example or a supporting point.\n- different — Different angle: The same message said a completely different way.\n- sarcastic — More sarcastic: Dry, witty and playfully mocking.\n- relatable — More relatable: Tie it to experiences everyone shares.\nDefault: None: your own instructions (leave it out).","type":"string","enum":["funnier","educational","urgent","professional","plug","shorter","longer","different","sarcastic","relatable"]},"instructions":{"description":"How to rewrite it, in your own words, at most 1000 characters. Use it with a preset or on its own. Example: \"mention that light cannot escape\".","type":"string","minLength":3,"maxLength":1000}},"additionalProperties":false},"example":{"preset":"funnier"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22"},{"name":"sceneNumber","in":"path","required":true,"schema":{"description":"The scene number: 1 for the first scene (ce_scenes list shows them).","type":"integer","minimum":1,"maximum":500},"description":"The scene number: 1 for the first scene (ce_scenes list shows them).","example":2},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"revision":{"description":"The project revision now: send it as expectedRevision with your next change.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sceneNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"speaker":{"anyOf":[{"type":"string"},{"type":"null"}]},"words":{"description":"What the scene says now.","type":"string"},"versions":{"type":"array","items":{"type":"object","properties":{"words":{"description":"A rewritten version: send it to update as words to use it.","type":"string"},"why":{"description":"What it changes, in a few words.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["words","why"],"additionalProperties":false}},"preset":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"],"additionalProperties":false},{"type":"null"}]},"nextStep":{"type":"string"}},"required":["projectId","revision","sceneNumber","speaker","words","versions","preset","nextStep"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","revision":1791796800000,"sceneNumber":2,"speaker":"Stewie Griffin","words":"So the star just falls into itself?","versions":[{"words":"So the star just eats itself? Like Dad at a buffet?","why":"Adds a family joke"},{"words":"Hold on, the star collapses into itself? Dramatic much?","why":"Sarcastic reaction"}],"preset":{"id":"funnier","label":"Make it funnier"},"nextStep":"To use a version, call update with sceneNumber 2, words set to it and expectedRevision 1791796800000."}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/projects/{projectId}/scenes/{sceneNumber}/sound-effect":{"put":{"operationId":"ce_scenes_set_sound_effect","summary":"Pick the sound effect a scene plays when it starts, or none. Free.","description":"Sets the sound effect played when a scene starts, from the app's sound effects (autoclips_options product=ce option=soundEffect lists them all), or `none` to take it off. Gameplay videos only. Only while the project is a draft; expectedRevision is required. The answer names the effect it replaced, so it can be put back. Free.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"ce.scenes.set_sound_effect","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_scenes action=set_sound_effect","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedRevision":{"description":"The project revision you last read (ce_projects get or ce_scenes list). If the project changed since, nothing is saved and you are told to read it again.","type":"integer","minimum":0,"maximum":9007199254740991},"effectId":{"title":"Scene sound effect (Character Explainer option soundEffect)","description":"Scene sound effect: A sound effect played when the scene starts, from the app's 112 effects in 8 kinds. Gameplay videos only. Free.\nOne of 113 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=ce&option=soundEffect) to see them all.\nChoices:\n- none — None: No sound effect on this scene.\n- futuristic-whoosh-hit-1 — Futuristic whoosh hit 1: Impacts: Futuristic whoosh transitioning into a heavy cinematic hit, sci-fi style\n- futuristic-whoosh-hit-2 — Futuristic whoosh hit 2: Impacts: Complex layered futuristic impact with trailing resonance\n- futuristic-whoosh-hit-3 — Futuristic whoosh hit 3: Impacts: Deep futuristic whoosh-to-hit with sub-bass impact\n- explosion-impact — Explosion impact: Impacts: Deep explosive impact with metallic resonance, like a distant explosion\n- sub-boom-impact — Sub boom impact: Impacts: Ultra-deep sub-bass boom that rumbles through, feels it in your chest\n- water-explosion — Water explosion: Impacts: Explosive splash impact with liquid burst texture\n- water-impact — Water impact: Impacts: Heavy water impact like something large hitting water\n- braam-1 — Braam 1: Impacts: Fat distorted cinematic braam, ominous and powerful like Inception\n- braam-2 — Braam 2: Impacts: Heavy brass braam with dark undertones, trailer-style impact\n- braam-3 — Braam 3: Impacts: Resonant braam with sustained power, builds and holds tension\n- 8bit-negative-1 — 8bit negative 1: Negatives: Retro 8-bit game failure sound, classic video game death/loss tone\n- 8bit-negative-2 — 8bit negative 2: Negatives: Descending 8-bit tone indicating something going wrong\n- 8bit-negative-3 — 8bit negative 3: Negatives: Short 8-bit error blip, quick negative feedback\n- 8bit-negative-4 — 8bit negative 4: Negatives: Buzzy 8-bit rejection sound with harsh tone\n- 8bit-negative-5 — 8bit negative 5: Negatives: Warped 8-bit failure with glitchy undertones\n- 8bit-negative-6 — 8bit negative 6: Negatives: Low 8-bit rumble suggesting impending doom\n- 8bit-negative-7 — 8bit negative 7: Negatives: Staccato 8-bit negative hits in quick succession\n- 8bit-negative-8 — 8bit negative 8: Negatives: Swooping down 8-bit sound like losing power\n- 8bit-negative-9 — 8bit negative 9: Negatives: Choppy 8-bit damage sound like taking hits\n- 8bit-negative-10 — 8bit negative 10: Negatives: Classic 8-bit game over melody, final failure\n- 8bit-negative-11 — 8bit negative 11: Negatives: Glitchy 8-bit crash sound with digital artifacts\n- 8bit-negative-12 — 8bit negative 12: Negatives: Dramatic 8-bit death sound with finality\n- man-saying-no-1 — Man saying no 1: Negatives: Male voice saying 'No' firmly and clearly\n- man-saying-no-2 — Man saying no 2: Negatives: Male voice saying 'No' with emphasis and frustration\n- man-saying-oh-no — Man saying oh no: Negatives: Male voice saying 'Oh no' with concern and worry\n- wrong-answer-1 — Wrong answer 1: Negatives: Classic game show wrong answer buzzer, harsh and final\n- wrong-answer-2 — Wrong answer 2: Negatives: Short wrong answer buzz, quick rejection sound\n- wrong-answer-3 — Wrong answer 3: Negatives: Double wrong answer buzz with two-tone failure\n- wrong-answer-4 — Wrong answer 4: Negatives: Low wrong answer buzz with deep, disappointing tone\n…and 83 more.","type":"string"}},"required":["expectedRevision","effectId"],"additionalProperties":false},"example":{"expectedRevision":1791796800000,"effectId":"big-casual-pop-1"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22"},{"name":"sceneNumber","in":"path","required":true,"schema":{"description":"The scene number: 1 for the first scene (ce_scenes list shows them).","type":"integer","minimum":1,"maximum":500},"description":"The scene number: 1 for the first scene (ce_scenes list shows them).","example":2},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"revision":{"description":"The project revision now: send it as expectedRevision with your next change.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sceneNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"soundEffect":{"description":"The effect now on the scene (null: none).","anyOf":[{"description":"A sound effect played when the scene starts.","type":"object","properties":{"id":{"description":"The effect id (the catalog option soundEffect).","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"description":"Its kind: impacts, whooshes, pop, …","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","description","category"],"additionalProperties":false},{"type":"null"}]},"previous":{"description":"The effect before (null: none). To undo, call set_sound_effect with its id, or none.","anyOf":[{"description":"A sound effect played when the scene starts.","type":"object","properties":{"id":{"description":"The effect id (the catalog option soundEffect).","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"description":"Its kind: impacts, whooshes, pop, …","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","description","category"],"additionalProperties":false},{"type":"null"}]},"changed":{"type":"boolean"}},"required":["projectId","revision","sceneNumber","soundEffect","previous","changed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","revision":1791796890000,"sceneNumber":2,"soundEffect":{"id":"big-casual-pop-1","description":"Big satisfying pop sound, like a balloon or bubble bursting","category":"pop"},"previous":null,"changed":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/projects/{projectId}/script":{"post":{"operationId":"ce_script_generate","summary":"Write the project's script from its topic, or split your own script into scenes. Free; it runs in the background as a job.","description":"Writes the scene-by-scene script from what is saved on the project: its topic (or your own pasted script, which is split between the characters and voiced as written), style, length, characters, language and script quality. Change those first with ce_projects update, and leave them alone in the app until the job finishes: the script follows the settings as they were when it started, and saving it puts the choice between a topic and your own script, the pasted script and the script quality back to those (the job result warns when a setting changed). Free, within the daily limit for free AI helpers. It takes a minute or two, so the answer is a job (kind ce.script): follow it with autoclips_jobs get. The job finishes once the new script and its title, description, tags and hashtags are saved, so the revision you read then stays put. Its result gives the opening lines, the number of scenes, the word count, about how long the script runs, whether it is longer than the length the video is paid for, and warnings to check; read the script itself with ce_script get. The first web link in a topic is read from the web while the script is written. Every link in the topic must be a public web page: a link to a private or internal address is refused. A project that already has a script needs replace: true: the new script replaces the current one and any changes made to its scenes, and its scene pictures and sound effects come off the scenes (the pictures stay in your media library, and ce_scenes set_picture can put them back on). In AI apps it asks first when it would take pictures or sound effects off. Writing a script also writes the video's title, description, tags and hashtags again. feedback tells the writer what to change (topic projects only). Only for a draft that nothing else is working on (no render, picture run, motion repair or other script run). Free plans get 30-second scripts with the Normal script quality, from a topic.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"ce.script.generate","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_script action=generate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"replace":{"description":"Must be true when the project already has a script: the new script replaces it and any changes made to its scenes, and its scene pictures and sound effects come off the scenes (the pictures stay in your media library). In AI apps it asks first when that takes pictures or sound effects off. Default: false.","type":"boolean"},"feedback":{"description":"What the writer should change this time, in your words (3 to 1000 characters), for example \"Make the ending funnier.\" Only for projects written from a topic; a pasted script is used as it is.","type":"string","minLength":3,"maxLength":1000}},"additionalProperties":false},"example":{"replace":true,"feedback":"Make the ending funnier."}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job":{"description":"The script job (kind ce.script). Follow it with autoclips_jobs get; when it has succeeded, its result is the summary described in ce_script generate.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"project":{"description":"The project as it is now (status writing_script).","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"ce"},"title":{"type":"string"},"status":{"description":"Where the project is: draft, writing_script, script_ready, needs_speakers, waiting_for_approval, making, prepared_in_app, finished, no_video, failed, stalled.","type":"string","enum":["draft","writing_script","script_ready","needs_speakers","waiting_for_approval","making","prepared_in_app","finished","no_video","failed","stalled"]},"statusText":{"description":"The status in plain words.","type":"string"},"step":{"description":"What is being made right now, while status is making.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"type":"number"},"revision":{"description":"Send it back as expectedRevision when you change scenes.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"appLink":{"description":"Where to open the project in the app.","type":"string"},"autoPost":{"description":"Where a finished render posts itself.","type":"object","properties":{"platforms":{"type":"array","items":{"type":"string"}}},"required":["platforms"],"additionalProperties":{}},"nextStep":{"description":"What to do next, in plain words.","type":"string"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","product","title","status","statusText","step","progress","revision","appLink","autoPost","nextStep","createdAt","updatedAt"],"additionalProperties":{}},"notes":{"description":"What to know about this run, in plain words.","type":"array","items":{"type":"string"}}},"required":["job","project","notes"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"job":{"id":"job_019a3c5e2b10c4d5e6f7a8b1","product":"ce","kind":"ce.script","resource":{"type":"project","id":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22"},"status":"running","step":"writing the script","progress":null,"result":null,"error":null,"createdAt":"2026-10-12T09:10:00.000Z","updatedAt":"2026-10-12T09:10:00.000Z","finishedAt":null,"poll_after_seconds":15},"project":{"id":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","product":"ce","title":"How black holes form","status":"writing_script","statusText":"Writing the script.","step":null,"progress":0,"revision":1791796200000,"appLink":"https://app.autoclips.app/character-explainer?sessionId=3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","autoPost":{"platforms":[]},"nextStep":"Wait for the script job (autoclips_jobs), then read it: ce_script get.","createdAt":"2026-10-12T09:00:00.000Z","updatedAt":"2026-10-12T09:10:00.000Z"},"notes":["When the new script is ready it replaces the current one (5 scenes) and any changes made to its scenes. Until then the current script stays as it is.","The video's title, description, tags and hashtags are written again for the new script, replacing the current ones.","Until the job finishes, leave this project's settings alone in the app: the script is written from the settings saved now, and saving it puts the choice between a topic and your own script, your own script and the script quality back to what they are now. The job result says if any setting changed.","Writing a script is free. It usually takes a minute or two: follow the job with autoclips_jobs get, then read the script with ce_script get."]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"ce_script_get","summary":"Read the project's script: its scenes, opening lines, word count, about how long it runs, and whether it fits the paid length.","description":"The script as saved: the scenes in order (number, who says it, the words, the picture idea, whether it has a picture or a sound effect, whether it needs a new voice), the opening lines the app suggested, and the project revision to send with scene changes. It also says how long the script is against the length the video is paid for: a script longer than the most words the paid length allows (125% of what the writer aims for at that length); for Japanese, Chinese and Thai, the most characters (about 500 for every 30 seconds) is refused at render (longerThanPaid), and lengthNote says what to do. Free.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"ce.script.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_script action=get","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"description":"The project the script belongs to.","type":"string"},"revision":{"description":"The project revision. Send it as expectedRevision when you change scenes (ce_scenes).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"description":"Where the project is (as ce_projects get says it).","type":"string","enum":["draft","writing_script","script_ready","needs_speakers","waiting_for_approval","making","prepared_in_app","finished","no_video","failed","stalled"]},"statusText":{"description":"The status in plain words.","type":"string"},"writing":{"description":"True while a new script is being written through the API.","type":"boolean"},"hasScript":{"description":"Whether the project has a script yet.","type":"boolean"},"hooks":{"description":"Up to three opening lines the app suggested, best first; the script opens with the one marked usedInScript.","type":"array","items":{"type":"object","properties":{"text":{"description":"The opening line.","type":"string"},"score":{"description":"How strong the app rates the line, from 0 to 10 (higher is better). Lines the AI writes usually score between 3 and 7; the first line of your own pasted script is always 10. Null when the app gave it no score.","anyOf":[{"type":"number"},{"type":"null"}]},"usedInScript":{"description":"True for the line the script opens with.","type":"boolean"}},"required":["text","score","usedInScript"],"additionalProperties":false}},"scenes":{"description":"The scenes in order.","type":"array","items":{"type":"object","properties":{"number":{"description":"The scene number: 1 for the first scene. Scene changes use it (ce_scenes).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"speaker":{"description":"The character who says it, or null when the scene names no speaker.","anyOf":[{"type":"string"},{"type":"null"}]},"words":{"description":"What is said in the scene.","type":"string"},"pictureIdea":{"description":"What the scene's picture could show; scene pictures are made from it.","anyOf":[{"type":"string"},{"type":"null"}]},"hasPicture":{"description":"Whether the scene has a picture or video on screen.","type":"boolean"},"soundEffect":{"description":"The scene's sound effect, or null.","anyOf":[{"type":"object","properties":{"id":{"description":"The sound effect's id, the one ce_scenes set_sound_effect takes.","type":"string"},"description":{"description":"What it sounds like, in a few words (null when the app has no words for it).","anyOf":[{"type":"string"},{"type":"null"}]},"category":{"description":"Its group, for example impacts or transitions (null when unknown).","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","description","category"],"additionalProperties":false},{"type":"null"}]},"needsNewVoice":{"description":"True when its words were changed after the script was written (here or in the app). The next render voices the words as they are now.","type":"boolean"}},"required":["number","speaker","words","pictureIdea","hasPicture","soundEffect","needsNewVoice"],"additionalProperties":false}},"words":{"description":"How long the script is, in words (or characters, see unit).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unit":{"description":"What the length is counted in: words, or characters for Japanese, Chinese and Thai.","type":"string","enum":["word","character"]},"estimatedSeconds":{"description":"About how many seconds the script takes to say.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"paidSeconds":{"description":"The length the video is paid for (the price band its length is billed at).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The most the script may hold at the paid length: the most words the paid length allows (125% of what the writer aims for at that length); for Japanese, Chinese and Thai, the most characters (about 500 for every 30 seconds).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"longerThanPaid":{"description":"True when the script is longer than limit: the render refuses it until the script is shorter (ce_scenes update) or, on a paid plan, the video is made longer (ce_projects update). lengthNote says which, for your plan.","type":"boolean"},"fitsSeconds":{"description":"The shortest paid length the script fits, or null when it is longer than the longest video.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"lengthNote":{"description":"When the script is longer than the paid length: what to do, in plain words.","anyOf":[{"type":"string"},{"type":"null"}]},"nextStep":{"description":"What to do next, in plain words.","type":"string"}},"required":["projectId","revision","status","statusText","writing","hasScript","hooks","scenes","words","unit","estimatedSeconds","paidSeconds","limit","longerThanPaid","fitsSeconds","lengthNote","nextStep"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"projectId":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","revision":1791795900000,"status":"script_ready","statusText":"Script ready. Next: pictures (optional), then render.","writing":false,"hasScript":true,"hooks":[{"text":"What happens when a star runs out of fuel?","score":6.5,"usedInScript":true},{"text":"Black holes are not holes at all.","score":5.1,"usedInScript":false},{"text":"A black hole is a star that fell into itself.","score":4.6,"usedInScript":false}],"scenes":[{"number":1,"speaker":"Peter Griffin","words":"What happens when a star runs out of fuel?","pictureIdea":"A huge glowing star in deep space","hasPicture":false,"soundEffect":null,"needsNewVoice":false},{"number":2,"speaker":"Stewie Griffin","words":"It just quietly goes dark, right?","pictureIdea":"Stewie raising an eyebrow","hasPicture":false,"soundEffect":null,"needsNewVoice":false},{"number":3,"speaker":"Peter Griffin","words":"When a giant star runs out of fuel, its core cannot hold up its own weight.","pictureIdea":"A star core shrinking fast","hasPicture":false,"soundEffect":null,"needsNewVoice":false},{"number":4,"speaker":"Peter Griffin","words":"It collapses into a point so dense that not even light gets out.","pictureIdea":"Light bending around a dark sphere","hasPicture":false,"soundEffect":null,"needsNewVoice":false},{"number":5,"speaker":"Stewie Griffin","words":"So a black hole is a star that fell into itself.","pictureIdea":"Stewie staring into a black hole","hasPicture":false,"soundEffect":null,"needsNewVoice":false}],"words":55,"unit":"word","estimatedSeconds":21,"paidSeconds":30,"limit":153,"longerThanPaid":false,"fitsSeconds":30,"lengthNote":null,"nextStep":"Check the scenes (ce_scenes list), add pictures if you like (ce_scenes generate_pictures), then render (ce_render start)."}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/projects/{projectId}/script/review":{"post":{"operationId":"ce_script_review","summary":"Approve or revise the script of a Quick Create that waits for your OK (reviewScript).","description":"For a Quick Create started with reviewScript: it stops after the script and waits. decision approve makes the video from that script (the scene pictures and sound effects asked for at Quick Create, if any, then the voices and the render), charged within the spending limit you approved at Quick Create; before it starts it checks your plan, your balance and that the rest still fits that limit. decision revise writes the script again with your feedback (a free AI helper, up to 5 times per project; a pasted script is used as it is, so it cannot be revised) and waits for your OK again. Each revision's feedback is added to the project's extra instructions, and the writer reads at most 1000 characters of them in all, so feedback that does not fit is refused and the answer says how much room is left. Read the script first with ce_script get. Answers with a new job for the rest of the run; the job you followed before ends and names the new one.\n\n**Permissions:** spend.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["spend"]}],"x-autoclips-operation":"ce.script.review","x-autoclips-scopes":["spend"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_script action=review","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"description":"approve: make the video from this script (the scene pictures and sound effects asked for at Quick Create, if any, then the voices and the render), within the spending limit you approved at Quick Create. revise: write the script again with your feedback; it waits for your OK again.","type":"string","enum":["approve","revise"]},"feedback":{"description":"What the writer should change this time, in your words (3 to 1000 characters), for example \"Make the ending funnier.\" Only for projects written from a topic; a pasted script is used as it is.","type":"string","minLength":3,"maxLength":1000}},"required":["decision"],"additionalProperties":false},"example":{"decision":"approve"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"9b2f4c1e-5d7a-4e3b-8c6f-1a2b3c4d5e6f"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"description":"running: the video is being made from the approved script. revising: the script is being written again; it waits for your OK again when it is ready.","type":"string","enum":["running","revising"]},"project":{"description":"The project.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"ce"},"title":{"type":"string"},"status":{"description":"Where the project is: draft, writing_script, script_ready, needs_speakers, waiting_for_approval, making, prepared_in_app, finished, no_video, failed, stalled.","type":"string","enum":["draft","writing_script","script_ready","needs_speakers","waiting_for_approval","making","prepared_in_app","finished","no_video","failed","stalled"]},"statusText":{"description":"The status in plain words.","type":"string"},"step":{"description":"What is being made right now, while status is making.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"type":"number"},"revision":{"description":"Send it back as expectedRevision when you change scenes.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"appLink":{"description":"Where to open the project in the app.","type":"string"},"autoPost":{"description":"Where a finished render posts itself.","type":"object","properties":{"platforms":{"type":"array","items":{"type":"string"}}},"required":["platforms"],"additionalProperties":{}},"nextStep":{"description":"What to do next, in plain words.","type":"string"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","product","title","status","statusText","step","progress","revision","appLink","autoPost","nextStep","createdAt","updatedAt"],"additionalProperties":{}},"job":{"description":"A new Quick Create job for the rest of the run: follow it with autoclips_jobs. The job you followed before ends (canceled, code continued) and names this one.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"revisionsLeft":{"description":"How many more times the script of this project can be revised.","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["status","project","job","revisionsLeft"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"status":"running","project":{"id":"9b2f4c1e-5d7a-4e3b-8c6f-1a2b3c4d5e6f","product":"ce","title":"How do black holes form?","status":"making","statusText":"Being made: Starting approved production (15%).","step":"Starting approved production","progress":15,"revision":1791795600000,"appLink":"https://app.autoclips.app/character-explainer?sessionId=9b2f4c1e-5d7a-4e3b-8c6f-1a2b3c4d5e6f","autoPost":{"platforms":[]},"nextStep":"Wait for the video: follow its job with autoclips_jobs, or read the project again.","createdAt":"2026-10-12T09:00:00.000Z","updatedAt":"2026-10-12T09:00:00.000Z","characters":[{"slug":"peter-griffin","name":"Peter Griffin","position":"bottom-left","personality":"authority","builtIn":true,"pictureUrl":"https://media.autoclips.app/characters/peter.png"}]},"job":{"id":"job_019ad7c3f0e8a1b2c3d4e5f6","product":"ce","kind":"ce.quick_create","resource":{"type":"project","id":"9b2f4c1e-5d7a-4e3b-8c6f-1a2b3c4d5e6f"},"status":"running","step":"Starting approved production","progress":15,"result":null,"error":null,"createdAt":"2026-10-12T09:00:00.000Z","updatedAt":"2026-10-12T09:00:00.000Z","finishedAt":null,"poll_after_seconds":10,"usualSeconds":450},"revisionsLeft":5}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/projects/{projectId}/seo":{"patch":{"operationId":"ce_seo_update","summary":"Change the title, description, tags or hashtags a finished video is posted with.","description":"Changes the post text of a finished video: its title, description, tags and hashtags. Send only what you want to change; the rest stays as saved. The video must be finished. A new render of the project writes new ones, replacing these, so change them after it finishes. Right after a video finishes the app writes its own for a minute or two; until then this answers \"try again in a few minutes\".\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"ce.seo.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_projects action=update_seo","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"The title the video is posted with. Example: \"How black holes are born\". At most 100 characters. Send \"\" to clear it; leave it out to keep the saved one.","type":"string","maxLength":100},"description":{"description":"The description the video is posted with. Example: \"A star runs out of fuel and collapses.\" At most 500 characters. Send \"\" to clear it; leave it out to keep the saved one.","type":"string","maxLength":500},"tags":{"description":"Keywords, separated by commas. Example: \"black holes, space, astronomy\". At most 2000 characters. Send \"\" to clear it; leave it out to keep the saved one.","type":"string","maxLength":2000},"hashtags":{"description":"Hashtags, separated by spaces. Example: \"#space #science\". At most 1000 characters. Send \"\" to clear it; leave it out to keep the saved one.","type":"string","maxLength":1000}},"additionalProperties":false},"example":{"title":"Black holes in 30 seconds"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"seo":{"description":"What is saved now.","type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"string"},"hashtags":{"type":"string"}},"required":["title","description","tags","hashtags"],"additionalProperties":false},"changed":{"description":"The fields whose text changed.","type":"array","items":{"type":"string","enum":["title","description","tags","hashtags"]}},"previous":{"description":"What was saved before (send it back to undo).","type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"string"},"hashtags":{"type":"string"}},"required":["title","description","tags","hashtags"],"additionalProperties":false}},"required":["projectId","seo","changed","previous"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13","seo":{"title":"Black holes in 30 seconds","description":"A star runs out of fuel, collapses, and a black hole is born. Peter explains it in 30 seconds.","tags":"black holes, space, astronomy, stars, physics, science","hashtags":"#space #blackhole #science #astronomy #learnontiktok"},"changed":["title"],"previous":{"title":"How black holes are born","description":"A star runs out of fuel, collapses, and a black hole is born. Peter explains it in 30 seconds.","tags":"black holes, space, astronomy, stars, physics, science","hashtags":"#space #blackhole #science #astronomy #learnontiktok"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/projects/{projectId}/sound-effects/suggest":{"post":{"operationId":"ce_sound_effects_suggest","summary":"Let an AI pick a sound effect for every scene, and put them on (or only suggest them).","description":"An AI reads the scenes and picks a kind of sound effect for each (an impact for a reveal, a pop for a light moment, …); one effect of that kind is put on each scene, replacing what was there. Each effect plays when its scene starts. With apply false nothing is saved. The answer lists what each scene had before, to undo with set_sound_effect. At most the first 60 scenes. Gameplay videos only, while the project is a draft (with apply false, a failed video too). Free, within the daily limit for free AI helpers: one call counts once, however long the script.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"ce.sound_effects.suggest","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_scenes action=suggest_sound_effects","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"apply":{"description":"true (the default): put the suggested sound effects on the scenes now (the answer lists what each scene had, to undo with set_sound_effect). false: only suggest; nothing is saved. Example: false.","type":"boolean"}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"revision":{"description":"The project revision now: send it as expectedRevision with your next change.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"applied":{"description":"Whether the effects were put on the scenes.","type":"boolean"},"scenes":{"description":"The scenes the AI picked a sound for.","type":"array","items":{"type":"object","properties":{"sceneNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"kind":{"description":"The kind of sound the AI picked (impacts, whooshes, pop, …).","type":"string"},"kindLabel":{"type":"string"},"reason":{"description":"Why, in a few words.","anyOf":[{"type":"string"},{"type":"null"}]},"soundEffect":{"description":"The effect picked for the scene.","type":"object","properties":{"id":{"description":"The effect id (the catalog option soundEffect).","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"description":"Its kind: impacts, whooshes, pop, …","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","description","category"],"additionalProperties":false},"previous":{"description":"What the scene had before (null: none).","anyOf":[{"description":"A sound effect played when the scene starts.","type":"object","properties":{"id":{"description":"The effect id (the catalog option soundEffect).","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"description":"Its kind: impacts, whooshes, pop, …","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","description","category"],"additionalProperties":false},{"type":"null"}]}},"required":["sceneNumber","kind","kindLabel","reason","soundEffect","previous"],"additionalProperties":false}},"notes":{"type":"array","items":{"type":"string"}}},"required":["projectId","revision","applied","scenes","notes"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"3f1c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a22","revision":1791796890000,"applied":true,"scenes":[{"sceneNumber":1,"kind":"impacts","kindLabel":"Impacts","reason":"dramatic opening fact","soundEffect":{"id":"futuristic-whoosh-hit-1","description":"Futuristic whoosh transitioning into a heavy cinematic hit, sci-fi style","category":"impacts"},"previous":{"id":"braam-1","description":"Fat distorted cinematic braam, ominous and powerful like Inception","category":"impacts"}},{"sceneNumber":2,"kind":"pop","kindLabel":"Pop","reason":"light question","soundEffect":{"id":"big-casual-pop-1","description":"Big satisfying pop sound, like a balloon or bubble bursting","category":"pop"},"previous":null},{"sceneNumber":3,"kind":"suspense","kindLabel":"Suspense","reason":"dark reveal","soundEffect":{"id":"sci-fi-drone-1","description":"Long atmospheric sci-fi drone with deep space ambience","category":"suspense"},"previous":null}],"notes":[]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ce/projects/{projectId}/versions":{"get":{"operationId":"ce_versions_list","summary":"Every version of a Character Explainer video: the original render and its edits, with links.","description":"Lists every version of a project's video, newest edit first and the original render last, in the app's words (\"Original video\", \"Edited video\"), each with a link and a thumbnail. Edits made in the Director Console belong to the project and are kept until expiresAt; edits the app's video editor saved are their own projects (projectId), which you open, post or delete by that id. A version still being made is listed as making, with no link yet; one that failed is left out. cover is the version the app's library shows for the project.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Character Explainer"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"ce.versions.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"ce_render action=versions","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Character Explainer project id (from ce_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Character Explainer project id (from ce_projects list or create).","example":"7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"editedFrom":{"description":"When this project is itself an edited copy: the project it was made from.","anyOf":[{"type":"string"},{"type":"null"}]},"cover":{"description":"The id of the version the app's library shows for this project.","anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"id":{"description":"\"original\" for the project's own render, the Director Console render's id, or the edited copy's project id.","type":"string"},"kind":{"description":"original: the project's own render. console_edit: an edit made in the Director Console. app_edit: an edit the app saved as its own project.","type":"string","enum":["original","console_edit","app_edit"]},"label":{"description":"What the app calls it.","type":"string"},"madeWith":{"description":"Where it came from, in plain words.","type":"string"},"status":{"description":"finished, or making (still being made: no link yet).","type":"string","enum":["finished","making"]},"videoUrl":{"description":"Where to watch it (null while it is being made).","anyOf":[{"type":"string"},{"type":"null"}]},"downloadUrl":{"description":"A download link for a Director Console version (null otherwise: download the video link).","anyOf":[{"type":"string"},{"type":"null"}]},"thumbnail":{"anyOf":[{"type":"string"},{"type":"null"}]},"thumbnailIsPlaceholder":{"description":"true when thumbnail is the character, not a frame of this video.","type":"boolean"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiresAt":{"description":"When a Director Console version is removed (null: kept like your other videos).","anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"projectId":{"description":"The project it belongs to (an edited copy is its own project).","type":"string"},"canPost":{"description":"Whether the API can post it (autoclips_publish).","type":"boolean"},"howToPost":{"type":"string"}},"required":["id","kind","label","madeWith","status","videoUrl","downloadUrl","thumbnail","thumbnailIsPlaceholder","createdAt","expiresAt","durationSeconds","projectId","canPost","howToPost"],"additionalProperties":false}}},"required":["projectId","editedFrom","cover","versions"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"projectId":"7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13","editedFrom":null,"cover":"original","versions":[{"id":"b8e05f3c-2a71-4c9d-8e46-1f3a7d5c9b20","kind":"app_edit","label":"Edited video","madeWith":"An edit the app's video editor saved as its own video: a separate project with its own id (projectId).","status":"finished","videoUrl":"https://media.autoclips.app/videos/character-explainer/b8e05f3c-2a71-4c9d-8e46-1f3a7d5c9b20.mp4","downloadUrl":null,"thumbnail":"https://media.autoclips.app/thumbnails/character-explainer/b8e05f3c-2a71-4c9d-8e46-1f3a7d5c9b20.jpg","thumbnailIsPlaceholder":false,"createdAt":"2026-10-11T14:00:00.000Z","expiresAt":null,"durationSeconds":null,"projectId":"b8e05f3c-2a71-4c9d-8e46-1f3a7d5c9b20","canPost":true,"howToPost":"Post it with autoclips_publish (product \"ce\", projectId \"b8e05f3c-2a71-4c9d-8e46-1f3a7d5c9b20\")."},{"id":"original","kind":"original","label":"Original video","madeWith":"The project's own render.","status":"finished","videoUrl":"https://media.autoclips.app/videos/character-explainer/7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13.mp4","downloadUrl":null,"thumbnail":"https://media.autoclips.app/thumbnails/character-explainer/7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13.jpg","thumbnailIsPlaceholder":false,"createdAt":"2026-10-10T08:20:00.000Z","expiresAt":null,"durationSeconds":null,"projectId":"7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13","canPost":true,"howToPost":"Post it with autoclips_publish (product \"ce\", projectId \"7c41e2a9-5b3d-4f8e-a1c6-0d9b2e4f6a13\")."}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connections":{"get":{"operationId":"shared_connections_list","summary":"List the AI apps connected to your account (Claude, ChatGPT and others).","description":"Shows every AI app that can act for your account: apps connected with the \"Connect AutoClips\" sign-in, and the MCP key from Settings → Claude if you made one. For each one: its name, when it connected, when it last renewed its access and what it may do. Only works from the AutoClips website while signed in.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.connections.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","parameters":[{"name":"limit","in":"query","required":false,"schema":{"description":"How many items to return (1–100, default 20).","type":"integer","minimum":1,"maximum":100},"description":"How many items to return (1–100, default 20)."},{"name":"cursor","in":"query","required":false,"schema":{"description":"The next_cursor from the previous page.","type":"string","maxLength":512},"description":"The next_cursor from the previous page."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"clientId":{"description":"The app's id. Use it to disconnect the app. The MCP key is always \"legacy_mcp_key\".","type":"string"},"clientName":{"description":"The name the app gave itself when it registered. Apps choose their own names, so it is not verified.","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"app = connected with the \"Connect AutoClips\" sign-in. mcp_key = the MCP key made in Settings → Claude.","type":"string","enum":["app","mcp_key"]},"keyLast4":{"description":"The last 4 characters of the MCP key, so you can tell which key it is. null for apps.","anyOf":[{"type":"string"},{"type":"null"}]},"firstConnectedAt":{"description":"The oldest sign-in record still kept for this app. For the MCP key, when it was made.","anyOf":[{"type":"string"},{"type":"null"}]},"lastIssuedAt":{"description":"When the app last got a fresh access token (it renews hourly while in use). For the MCP key, when it was made.","anyOf":[{"type":"string"},{"type":"null"}]},"expiresAt":{"description":"When the app loses access if it stops renewing. null for the MCP key, which works until you delete it.","anyOf":[{"type":"string"},{"type":"null"}]},"scopes":{"description":"What the app is allowed to do.","type":"array","items":{"type":"string","enum":["read","edit","spend","delete","publish"]}}},"required":["clientId","clientName","kind","keyLast4","firstConnectedAt","lastIssuedAt","expiresAt","scopes"],"additionalProperties":false}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"has_more":{"type":"boolean"}},"required":["items","next_cursor","has_more"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"items":[{"clientId":"acmc_3f9a0c1d2e4b5a6978c0d1e2f3a4b5c6","clientName":"Claude","kind":"app","keyLast4":null,"firstConnectedAt":"2026-09-20T09:14:00.000Z","lastIssuedAt":"2026-09-28T10:02:00.000Z","expiresAt":"2026-12-27T10:02:00.000Z","scopes":["read","edit","spend","delete","publish"]},{"clientId":"legacy_mcp_key","clientName":"MCP key (Settings → Claude)","kind":"mcp_key","keyLast4":"9f2c","firstConnectedAt":"2026-08-02T16:40:00.000Z","lastIssuedAt":"2026-08-02T16:40:00.000Z","expiresAt":null,"scopes":["read","edit","spend","delete","publish"]}],"next_cursor":null,"has_more":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connections/{clientId}":{"delete":{"operationId":"shared_connections_revoke","summary":"Disconnect an AI app or delete your MCP key. It loses access right away.","description":"Disconnects the app right away: every access token, refresh token and pending sign-in it holds for your account is deleted, so its next request is refused and it cannot renew. To use it again, connect it again from the app. Use the id \"legacy_mcp_key\" to delete the MCP key made in Settings → Claude; anything using that key stops working at once. Other people who use the same app are not affected. Rare case: if the app was renewing its access at the very moment you disconnected it, it can keep one fresh token. If it still shows in the list, disconnect it again.\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["Account, media and publishing"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"shared.connections.revoke","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"clientId","in":"path","required":true,"schema":{"description":"clientId","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"clientId","example":"acmc_3f9a0c1d2e4b5a6978c0d1e2f3a4b5c6"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"clientId":{"type":"string"},"clientName":{"anyOf":[{"type":"string"},{"type":"null"}]},"disconnected":{"type":"boolean"},"tokensDeleted":{"description":"Access and refresh tokens deleted (1 when the MCP key was deleted).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"codesDeleted":{"description":"Pending sign-ins deleted.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["clientId","clientName","disconnected","tokensDeleted","codesDeleted"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"clientId":"acmc_3f9a0c1d2e4b5a6978c0d1e2f3a4b5c6","clientName":"Claude","disconnected":true,"tokensDeleted":2,"codesDeleted":0}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/covers/{product}/{projectId}":{"get":{"operationId":"shared_covers_get","summary":"The thumbnail (cover) of a finished V3 or Character Explainer video: the picture, its words, and the price of a new one.","description":"Shows the cover every post of the video carries (on YouTube, TikTok, Instagram and Facebook; X and Snapchat show their own frame). A finished video gets one drawn by itself; change it with draw (a new picture, costs credits), words (new words on the same picture, free) or upload (your own picture, free). The library on the website shows and changes the same cover.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.covers.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_covers action=get","parameters":[{"name":"product","in":"path","required":true,"schema":{"description":"Which kind of video: v3 (an AutoClips V3 story) or ce (a Character Explainer video).","type":"string","enum":["v3","ce"]},"description":"Which kind of video: v3 (an AutoClips V3 story) or ce (a Character Explainer video).","example":"v3"},{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id (v3_projects list or ce_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The project id (v3_projects list or ce_projects list).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"cover":{"type":"object","properties":{"product":{"type":"string","enum":["v3","ce"]},"projectId":{"type":"string"},"status":{"description":"none (no cover yet), drawing (a new picture is being made), writing (words are being laid on), ready, or failed (the last change failed; the cover before it, if any, is still the one posted).","type":"string","enum":["none","drawing","writing","ready","failed"]},"url":{"description":"The cover picture. Every later post of the video carries it.","anyOf":[{"type":"string"},{"type":"null"}]},"from":{"description":"ai: drawn by AutoClips, with its words laid on; yours: a picture you uploaded, used as it is.","anyOf":[{"type":"string","enum":["ai","yours"]},{"type":"null"}]},"topLine":{"description":"The short line above the words (usually empty).","type":"string"},"title":{"description":"The words on the cover.","type":"string"},"idea":{"description":"What its picture was asked to show, when you said.","anyOf":[{"type":"string"},{"type":"null"}]},"error":{"description":"Why the last change failed, in plain words.","anyOf":[{"type":"string"},{"type":"null"}]},"defaults":{"description":"The words a new cover starts from: the video's own title.","type":"object","properties":{"topLine":{"type":"string"},"title":{"type":"string"}},"required":["topLine","title"],"additionalProperties":false},"creditsForNewPicture":{"description":"What draw costs on this video. Words and your own picture are free.","type":"integer","minimum":0,"maximum":9007199254740991},"canMake":{"description":"false until the video is finished.","type":"boolean"},"canChangeWords":{"description":"true when the cover is a drawn picture whose words can be changed (an uploaded one is used as it is).","type":"boolean"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["product","projectId","status","url","from","topLine","title","idea","error","defaults","creditsForNewPicture","canMake","canChangeWords","updatedAt"],"additionalProperties":false}},"required":["cover"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"cover":{"product":"v3","projectId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","status":"ready","url":"https://media.autoclips.app/stickman-keyframes/thumbnails/v3/b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/cover-mgx1a2b3c.jpg","from":"ai","topLine":"","title":"The Last Lighthouse","idea":null,"error":null,"defaults":{"topLine":"","title":"The Last Lighthouse"},"creditsForNewPicture":20,"canMake":true,"canChangeWords":true,"updatedAt":"2026-10-25T10:00:00.000Z"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/covers/{product}/{projectId}/draw":{"post":{"operationId":"shared_covers_draw","summary":"Draw a new thumbnail picture for a finished video, with its words laid on. Costs credits; answers with a job.","description":"An AI draws a new 9:16 cover from the video's own characters and look (idea says what it shows), and its words are laid on it (title, and an optional topLine). It replaces the cover when it is done, and every later post of the video carries it. Charged only when the new cover exists; a failed one costs nothing and keeps the cover before it. One change at a time on a video. The video must be finished.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"shared.covers.draw","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"autoclips_covers action=draw","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idea":{"description":"What the picture should show, in your own words (3 to 300 characters). Leave it out to let it pick a strong moment from the video.","type":"string","minLength":3,"maxLength":300},"title":{"description":"The words on the cover (up to 48 characters). Leave it out to keep the cover's words, or the video's title.","type":"string","maxLength":48},"topLine":{"description":"A short line above the words (up to 24 characters, for example \"PART 2\"; a number at its end is drawn big). Usually empty.","type":"string","maxLength":24},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{"idea":"The keeper at the top of the stairs, lamp in hand, a storm behind the glass"}}}},"parameters":[{"name":"product","in":"path","required":true,"schema":{"description":"Which kind of video: v3 (an AutoClips V3 story) or ce (a Character Explainer video).","type":"string","enum":["v3","ce"]},"description":"Which kind of video: v3 (an AutoClips V3 story) or ce (a Character Explainer video).","example":"v3"},{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id (v3_projects list or ce_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The project id (v3_projects list or ce_projects list).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"cover":{"type":"object","properties":{"product":{"type":"string","enum":["v3","ce"]},"projectId":{"type":"string"},"status":{"description":"none (no cover yet), drawing (a new picture is being made), writing (words are being laid on), ready, or failed (the last change failed; the cover before it, if any, is still the one posted).","type":"string","enum":["none","drawing","writing","ready","failed"]},"url":{"description":"The cover picture. Every later post of the video carries it.","anyOf":[{"type":"string"},{"type":"null"}]},"from":{"description":"ai: drawn by AutoClips, with its words laid on; yours: a picture you uploaded, used as it is.","anyOf":[{"type":"string","enum":["ai","yours"]},{"type":"null"}]},"topLine":{"description":"The short line above the words (usually empty).","type":"string"},"title":{"description":"The words on the cover.","type":"string"},"idea":{"description":"What its picture was asked to show, when you said.","anyOf":[{"type":"string"},{"type":"null"}]},"error":{"description":"Why the last change failed, in plain words.","anyOf":[{"type":"string"},{"type":"null"}]},"defaults":{"description":"The words a new cover starts from: the video's own title.","type":"object","properties":{"topLine":{"type":"string"},"title":{"type":"string"}},"required":["topLine","title"],"additionalProperties":false},"creditsForNewPicture":{"description":"What draw costs on this video. Words and your own picture are free.","type":"integer","minimum":0,"maximum":9007199254740991},"canMake":{"description":"false until the video is finished.","type":"boolean"},"canChangeWords":{"description":"true when the cover is a drawn picture whose words can be changed (an uploaded one is used as it is).","type":"boolean"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["product","projectId","status","url","from","topLine","title","idea","error","defaults","creditsForNewPicture","canMake","canChangeWords","updatedAt"],"additionalProperties":false},"job":{"description":"Follow it with autoclips_jobs get (or GET /v1/jobs/{id}). Its result has the new cover's url.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false}},"required":["cover","job"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"cover":{"product":"v3","projectId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","status":"drawing","url":"https://media.autoclips.app/stickman-keyframes/thumbnails/v3/b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/cover-mgx1a2b3c.jpg","from":"ai","topLine":"","title":"The Last Lighthouse","idea":null,"error":null,"defaults":{"topLine":"","title":"The Last Lighthouse"},"creditsForNewPicture":20,"canMake":true,"canChangeWords":true,"updatedAt":"2026-10-25T10:00:00.000Z"},"job":{"id":"job_0199d81a2b3c4d5e6f7081a0","product":"shared","kind":"shared.cover","resource":{"type":"cover","id":"v3:b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},"status":"running","step":"Drawing the picture","progress":10,"result":null,"error":null,"createdAt":"2026-10-25T10:05:00.000Z","updatedAt":"2026-10-25T10:05:00.000Z","finishedAt":null,"poll_after_seconds":10,"usualSeconds":40}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/covers/{product}/{projectId}/upload":{"post":{"operationId":"shared_covers_upload","summary":"Make a picture from your media library the video's thumbnail, used as it is. Free.","description":"Makes one of your pictures the cover of a finished video: kept as it is (never cropped, so its own words stay), turned upright and saved as a JPEG of at most 2 MB, the largest YouTube takes. Every later post of the video carries it. Bring the file in with autoclips_media first. Free; counts toward the daily limit of uploads.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.covers.upload","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_covers action=upload","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mediaId":{"description":"A picture in your media library (autoclips_media upload, upload_link or import_url): JPG, PNG or WebP, at least 300 pixels a side; 1080 x 1920 is best.","type":"string","pattern":"^[a-fA-F0-9]{24}$"}},"required":["mediaId"],"additionalProperties":false},"example":{"mediaId":"66f7c0ffee00000000000001"}}}},"parameters":[{"name":"product","in":"path","required":true,"schema":{"description":"Which kind of video: v3 (an AutoClips V3 story) or ce (a Character Explainer video).","type":"string","enum":["v3","ce"]},"description":"Which kind of video: v3 (an AutoClips V3 story) or ce (a Character Explainer video).","example":"ce"},{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id (v3_projects list or ce_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The project id (v3_projects list or ce_projects list).","example":"ce_1727600000000_ab12cd"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"cover":{"type":"object","properties":{"product":{"type":"string","enum":["v3","ce"]},"projectId":{"type":"string"},"status":{"description":"none (no cover yet), drawing (a new picture is being made), writing (words are being laid on), ready, or failed (the last change failed; the cover before it, if any, is still the one posted).","type":"string","enum":["none","drawing","writing","ready","failed"]},"url":{"description":"The cover picture. Every later post of the video carries it.","anyOf":[{"type":"string"},{"type":"null"}]},"from":{"description":"ai: drawn by AutoClips, with its words laid on; yours: a picture you uploaded, used as it is.","anyOf":[{"type":"string","enum":["ai","yours"]},{"type":"null"}]},"topLine":{"description":"The short line above the words (usually empty).","type":"string"},"title":{"description":"The words on the cover.","type":"string"},"idea":{"description":"What its picture was asked to show, when you said.","anyOf":[{"type":"string"},{"type":"null"}]},"error":{"description":"Why the last change failed, in plain words.","anyOf":[{"type":"string"},{"type":"null"}]},"defaults":{"description":"The words a new cover starts from: the video's own title.","type":"object","properties":{"topLine":{"type":"string"},"title":{"type":"string"}},"required":["topLine","title"],"additionalProperties":false},"creditsForNewPicture":{"description":"What draw costs on this video. Words and your own picture are free.","type":"integer","minimum":0,"maximum":9007199254740991},"canMake":{"description":"false until the video is finished.","type":"boolean"},"canChangeWords":{"description":"true when the cover is a drawn picture whose words can be changed (an uploaded one is used as it is).","type":"boolean"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["product","projectId","status","url","from","topLine","title","idea","error","defaults","creditsForNewPicture","canMake","canChangeWords","updatedAt"],"additionalProperties":false}},"required":["cover"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"cover":{"product":"ce","projectId":"ce_1727600000000_ab12cd","status":"ready","url":"https://media.autoclips.app/stickman-keyframes/thumbnails/character-explainer/ce_1727600000000_ab12cd/own-3f9a0c1b2d4e5f60718293a4.jpg","from":"yours","topLine":"","title":"","idea":null,"error":null,"defaults":{"topLine":"","title":"Why is the sky blue?"},"creditsForNewPicture":20,"canMake":true,"canChangeWords":false,"updatedAt":"2026-10-25T10:00:00.000Z"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/covers/{product}/{projectId}/words":{"post":{"operationId":"shared_covers_words","summary":"Change the words on a video's thumbnail, keeping its picture. Free; answers with a job.","description":"Lays new words on the picture the cover already has (title, and an optional topLine) and makes that the cover. Free; counts toward the daily limit of finishing passes. Only for a drawn cover (an uploaded picture is used as it is: draw a new one to put words on it).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.covers.words","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_covers action=words","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"The words on the cover (up to 48 characters). Leave it out to keep the cover's words, or the video's title.","type":"string","maxLength":48},"topLine":{"description":"A short line above the words (up to 24 characters, for example \"PART 2\"; a number at its end is drawn big). Usually empty.","type":"string","maxLength":24}},"required":["title"],"additionalProperties":false},"example":{"title":"He Never Came Down"}}}},"parameters":[{"name":"product","in":"path","required":true,"schema":{"description":"Which kind of video: v3 (an AutoClips V3 story) or ce (a Character Explainer video).","type":"string","enum":["v3","ce"]},"description":"Which kind of video: v3 (an AutoClips V3 story) or ce (a Character Explainer video).","example":"v3"},{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id (v3_projects list or ce_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The project id (v3_projects list or ce_projects list).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"cover":{"type":"object","properties":{"product":{"type":"string","enum":["v3","ce"]},"projectId":{"type":"string"},"status":{"description":"none (no cover yet), drawing (a new picture is being made), writing (words are being laid on), ready, or failed (the last change failed; the cover before it, if any, is still the one posted).","type":"string","enum":["none","drawing","writing","ready","failed"]},"url":{"description":"The cover picture. Every later post of the video carries it.","anyOf":[{"type":"string"},{"type":"null"}]},"from":{"description":"ai: drawn by AutoClips, with its words laid on; yours: a picture you uploaded, used as it is.","anyOf":[{"type":"string","enum":["ai","yours"]},{"type":"null"}]},"topLine":{"description":"The short line above the words (usually empty).","type":"string"},"title":{"description":"The words on the cover.","type":"string"},"idea":{"description":"What its picture was asked to show, when you said.","anyOf":[{"type":"string"},{"type":"null"}]},"error":{"description":"Why the last change failed, in plain words.","anyOf":[{"type":"string"},{"type":"null"}]},"defaults":{"description":"The words a new cover starts from: the video's own title.","type":"object","properties":{"topLine":{"type":"string"},"title":{"type":"string"}},"required":["topLine","title"],"additionalProperties":false},"creditsForNewPicture":{"description":"What draw costs on this video. Words and your own picture are free.","type":"integer","minimum":0,"maximum":9007199254740991},"canMake":{"description":"false until the video is finished.","type":"boolean"},"canChangeWords":{"description":"true when the cover is a drawn picture whose words can be changed (an uploaded one is used as it is).","type":"boolean"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["product","projectId","status","url","from","topLine","title","idea","error","defaults","creditsForNewPicture","canMake","canChangeWords","updatedAt"],"additionalProperties":false},"job":{"description":"Follow it with autoclips_jobs get (or GET /v1/jobs/{id}). Its result has the new cover's url.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false}},"required":["cover","job"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"cover":{"product":"v3","projectId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","status":"writing","url":"https://media.autoclips.app/stickman-keyframes/thumbnails/v3/b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/cover-mgx1a2b3c.jpg","from":"ai","topLine":"","title":"The Last Lighthouse","idea":null,"error":null,"defaults":{"topLine":"","title":"The Last Lighthouse"},"creditsForNewPicture":20,"canMake":true,"canChangeWords":true,"updatedAt":"2026-10-25T10:00:00.000Z"},"job":{"id":"job_0199d81a2b3c4d5e6f7081a0","product":"shared","kind":"shared.cover","resource":{"type":"cover","id":"v3:b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},"status":"running","step":"Writing the words","progress":50,"result":null,"error":null,"createdAt":"2026-10-25T10:06:00.000Z","updatedAt":"2026-10-25T10:06:00.000Z","finishedAt":null,"poll_after_seconds":3,"usualSeconds":5}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credits":{"get":{"operationId":"shared_credits_get","summary":"Your credit balance, plan and plan limits.","description":"Returns the balance your videos spend from, your plan (planName says it in words), how the balance splits into plan credits and bought credits, plan limits such as the longest AutoClips V3 video you can make, and the daily limit of the account for API keys and AI apps with what counts against it today. notes says the plan, the limit and what the plan leaves out in plain words. To see what one video would cost, ask for a quote.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.credits.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_account action=credits","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"balance":{"description":"The credits your videos spend from: videoCredits on a lifetime plan, v2credits on every other plan.","type":"number"},"creditField":{"description":"Which of the two balances `balance` is.","type":"string","enum":["v2credits","videoCredits"]},"plan":{"description":"Your plan id, for example \"pro-monthly\" or \"lifetime-basic\". null on the free plan. planName says it in words.","anyOf":[{"type":"string"},{"type":"null"}]},"planName":{"description":"Your plan in plain words: \"free plan\", \"Pro plan (monthly)\", \"Pro lifetime plan\".","type":"string"},"isLifetime":{"type":"boolean"},"hasActiveSubscription":{"description":"True when your account has a paid plan (a subscription, a lifetime licence or a legacy account). A subscription that ended is the free plan again.","type":"boolean"},"subscriptionCredits":{"description":"The part of v2credits that came with your plan. It is spent first and resets with your plan.","type":"number"},"purchasedCredits":{"description":"The part of v2credits you bought. It is spent after the plan credits.","type":"number"},"balances":{"description":"Both balances. Lifetime plans have two; other plans only use v2credits.","type":"object","properties":{"v2credits":{"type":"number"},"videoCredits":{"type":"number"}},"required":["v2credits","videoCredits"],"additionalProperties":false},"limits":{"type":"object","properties":{"v3":{"type":"object","properties":{"maxDurationSeconds":{"description":"Longest AutoClips V3 video your plan allows. 0 means V3 is not on your plan (on the free plan: V3 needs a paid plan); notes says so in words.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"allowedDurationsSeconds":{"description":"The V3 video lengths you can pick.","type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["maxDurationSeconds","allowedDurationsSeconds"],"additionalProperties":false}},"required":["v3"],"additionalProperties":false},"dailyLimit":{"description":"The account's daily limit for API keys and AI apps (the same numbers as whoami).","type":"object","properties":{"credits":{"description":"The most this account may spend in a UTC day through API keys and AI apps together. null when signed in on the website, which has no limit. Change it in Settings → API.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"spentToday":{"description":"Credits counted against that limit today (UTC).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["credits","spentToday"],"additionalProperties":false},"notes":{"description":"The plan, the daily limit and what the plan leaves out, in plain words.","type":"array","items":{"type":"string"}}},"required":["balance","creditField","plan","planName","isLifetime","hasActiveSubscription","subscriptionCredits","purchasedCredits","balances","limits","dailyLimit","notes"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"balance":1850,"creditField":"v2credits","plan":"pro-monthly","planName":"Pro plan (monthly)","isLifetime":false,"hasActiveSubscription":true,"subscriptionCredits":1350,"purchasedCredits":500,"balances":{"v2credits":1850,"videoCredits":0},"limits":{"v3":{"maxDurationSeconds":180,"allowedDurationsSeconds":[60,65,75,90,100,120,180]}},"dailyLimit":{"credits":6000,"spentToday":240},"notes":["Daily limit for API keys and AI apps together: 6,000 credits, 240 used today (it starts again at 00:00 UTC; change it in Settings → API)."]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credits/auto-top-up":{"get":{"operationId":"shared_credits_auto_top_up_get","summary":"Your auto top-up: whether it refills your credits from your card, when, with which pack, and the card.","description":"Returns your auto top-up setting: when your balance drops below thresholdCredits, the card is charged amountUsd and the pack's credits are added, at most maxPerMonth times a calendar month (UTC). Also the balance, how many top-ups were charged this month, the card on file (the card saved for auto top-up, or the card your plan is paid with) and, when it is paused, why. Change it with set_auto_top_up (PUT /credits/auto-top-up). Free.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.credits.auto_top_up.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_account action=auto_top_up","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"autoTopUp":{"type":"object","properties":{"enabled":{"description":"Whether auto top-up is switched on.","type":"boolean"},"state":{"description":"off; on; paused (a charge failed: a card must be added on the website); limit_reached (this month's top-ups are used: it starts again at resetsAt).","type":"string","enum":["off","on","paused","limit_reached"]},"thresholdCredits":{"description":"It refills when the balance drops below this.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amountUsd":{"description":"The pack each top-up buys, in US dollars.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"credits":{"description":"Credits each top-up adds (bonus included).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bonusPercent":{"description":"The pack's bonus, in percent.","type":"number"},"maxPerMonth":{"description":"The most top-ups in a calendar month (UTC).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"monthlyLimitUsd":{"description":"amountUsd times maxPerMonth: the most it can charge in a month.","type":"number"},"usedThisMonth":{"description":"Top-ups charged this month (one still settling counts).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"resetsAt":{"description":"When the monthly count starts again (ISO 8601, UTC).","type":"string"},"card":{"description":"The card saved for auto top-up, or null.","anyOf":[{"type":"object","properties":{"brand":{"description":"visa, mastercard, amex, ...","type":"string"},"last4":{"type":"string"},"expMonth":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"expYear":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"country":{"description":"Where the card was issued (two letters), when known. Banks in India ask to confirm automatic charges, so auto top-up may pause on an Indian card.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["brand","last4","expMonth","expYear","country"],"additionalProperties":false},{"type":"null"}]},"pausedReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"description":"Why it is paused and what to do, in plain words.","anyOf":[{"type":"string"},{"type":"null"}]},"lastCharge":{"anyOf":[{"type":"object","properties":{"amountUsd":{"type":"number"},"credits":{"type":"number"},"at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["amountUsd","credits","at"],"additionalProperties":false},{"type":"null"}]}},"required":["enabled","state","thresholdCredits","amountUsd","credits","bonusPercent","maxPerMonth","monthlyLimitUsd","usedThisMonth","resetsAt","card","pausedReason","message","lastCharge"],"additionalProperties":false},"balance":{"description":"The credit balance now.","type":"number"},"eligible":{"description":"Whether the account may switch it on (a paid plan).","type":"boolean"},"cardOnFile":{"description":"The card a charge would use if it were switched on now. null: a card must be added on the website (addCardUrl).","anyOf":[{"type":"object","properties":{"brand":{"description":"visa, mastercard, amex, ...","type":"string"},"last4":{"type":"string"},"expMonth":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"expYear":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"country":{"description":"Where the card was issued (two letters), when known. Banks in India ask to confirm automatic charges, so auto top-up may pause on an Indian card.","anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"auto_top_up: saved for auto top-up; plan: the card the plan is paid with.","type":"string","enum":["auto_top_up","plan"]}},"required":["brand","last4","expMonth","expYear","country","source"],"additionalProperties":false},{"type":"null"}]},"addCardUrl":{"description":"Where the person adds or changes the card (website only).","type":"string"},"notes":{"description":"The setting in plain words.","type":"array","items":{"type":"string"}}},"required":["autoTopUp","balance","eligible","cardOnFile","addCardUrl","notes"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"autoTopUp":{"enabled":true,"state":"on","thresholdCredits":2000,"amountUsd":100,"credits":47250,"bonusPercent":5,"maxPerMonth":3,"monthlyLimitUsd":300,"usedThisMonth":1,"resetsAt":"2026-11-01T00:00:00.000Z","card":{"brand":"visa","last4":"4242","expMonth":10,"expYear":2028,"country":"US"},"pausedReason":null,"message":null,"lastCharge":{"amountUsd":100,"credits":47250,"at":"2026-10-21T09:14:03.000Z"}},"balance":38120,"eligible":true,"cardOnFile":{"brand":"visa","last4":"4242","expMonth":10,"expYear":2028,"country":"US","source":"auto_top_up"},"addCardUrl":"https://app.autoclips.app/credits?autoTopUp=setup","notes":["When your balance drops below 2,000 credits, we charge $100 to Visa ending 4242 and add 47,250 credits. At most 3 a month ($300); 1 used this month."]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"shared_credits_auto_top_up_set","summary":"Switch auto top-up on or off, or change when it refills, which pack it buys and how many times a month.","description":"Switches auto top-up on (enabled true) or off (enabled false), and saves any of thresholdCredits, amountUsd and maxPerMonth you send; the rest stay as saved. On, the card is charged amountUsd whenever the balance drops below thresholdCredits, and the pack's credits are added (they never expire), at most maxPerMonth times a calendar month (UTC) and never twice within 10 minutes. A declined card pauses it until a card is added on the website. It charges the card saved for auto top-up, or (card: plan, or when none is saved) the card your plan is paid with; a new card can only be added on the website (addCardUrl). Switched on while the balance is already below the line, the first top-up is charged right away. Switching on, a bigger pack or more top-ups a month asks first in AI apps; switching off never does. Needs the edit and spend permissions. The change itself is free.\n\n**Permissions:** edit, spend.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"shared.credits.auto_top_up.set","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_account action=set_auto_top_up","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"description":"true switches auto top-up on (or keeps it on); false switches it off. Off, nothing is ever charged.","type":"boolean"},"thresholdCredits":{"description":"Refill when the balance drops below this many credits: 1,000, 2,000, 5,000, 10,000, 20,000. It must be below what the pack adds. Leave it out to keep the saved one (2,000 the first time).","anyOf":[{"type":"number","enum":[1000,2000,5000,10000,20000]},{"type":"string","pattern":"^(?:1000|2000|5000|10000|20000)$"}]},"amountUsd":{"description":"The pack each top-up buys, in US dollars: $10 (4,500 credits), $25 (11,250 credits), $50 (22,500 credits), $100 (47,250 credits, +5%), $200 (99,000 credits, +10%). Leave it out to keep the saved one ($100 the first time).","anyOf":[{"type":"number","enum":[10,25,50,100,200]},{"type":"string","pattern":"^(?:10|25|50|100|200)$"}]},"maxPerMonth":{"description":"The most top-ups in a calendar month (UTC): 1, 2, 3, 5, 10. Leave it out to keep the saved one (3 the first time).","anyOf":[{"type":"number","enum":[1,2,3,5,10]},{"type":"string","pattern":"^(?:1|2|3|5|10)$"}]},"card":{"description":"Which card to charge: saved (the card saved for auto top-up) or plan (the card your plan is paid with). Leave it out for the saved card, else the plan's.","type":"string","enum":["saved","plan"]}},"required":["enabled"],"additionalProperties":false},"example":{"enabled":true,"thresholdCredits":2000,"amountUsd":100,"maxPerMonth":3}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"autoTopUp":{"type":"object","properties":{"enabled":{"description":"Whether auto top-up is switched on.","type":"boolean"},"state":{"description":"off; on; paused (a charge failed: a card must be added on the website); limit_reached (this month's top-ups are used: it starts again at resetsAt).","type":"string","enum":["off","on","paused","limit_reached"]},"thresholdCredits":{"description":"It refills when the balance drops below this.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amountUsd":{"description":"The pack each top-up buys, in US dollars.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"credits":{"description":"Credits each top-up adds (bonus included).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bonusPercent":{"description":"The pack's bonus, in percent.","type":"number"},"maxPerMonth":{"description":"The most top-ups in a calendar month (UTC).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"monthlyLimitUsd":{"description":"amountUsd times maxPerMonth: the most it can charge in a month.","type":"number"},"usedThisMonth":{"description":"Top-ups charged this month (one still settling counts).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"resetsAt":{"description":"When the monthly count starts again (ISO 8601, UTC).","type":"string"},"card":{"description":"The card saved for auto top-up, or null.","anyOf":[{"type":"object","properties":{"brand":{"description":"visa, mastercard, amex, ...","type":"string"},"last4":{"type":"string"},"expMonth":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"expYear":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"country":{"description":"Where the card was issued (two letters), when known. Banks in India ask to confirm automatic charges, so auto top-up may pause on an Indian card.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["brand","last4","expMonth","expYear","country"],"additionalProperties":false},{"type":"null"}]},"pausedReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"description":"Why it is paused and what to do, in plain words.","anyOf":[{"type":"string"},{"type":"null"}]},"lastCharge":{"anyOf":[{"type":"object","properties":{"amountUsd":{"type":"number"},"credits":{"type":"number"},"at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["amountUsd","credits","at"],"additionalProperties":false},{"type":"null"}]}},"required":["enabled","state","thresholdCredits","amountUsd","credits","bonusPercent","maxPerMonth","monthlyLimitUsd","usedThisMonth","resetsAt","card","pausedReason","message","lastCharge"],"additionalProperties":false},"balance":{"description":"The credit balance now.","type":"number"},"eligible":{"description":"Whether the account may switch it on (a paid plan).","type":"boolean"},"cardOnFile":{"description":"The card a charge would use if it were switched on now. null: a card must be added on the website (addCardUrl).","anyOf":[{"type":"object","properties":{"brand":{"description":"visa, mastercard, amex, ...","type":"string"},"last4":{"type":"string"},"expMonth":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"expYear":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"country":{"description":"Where the card was issued (two letters), when known. Banks in India ask to confirm automatic charges, so auto top-up may pause on an Indian card.","anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"auto_top_up: saved for auto top-up; plan: the card the plan is paid with.","type":"string","enum":["auto_top_up","plan"]}},"required":["brand","last4","expMonth","expYear","country","source"],"additionalProperties":false},{"type":"null"}]},"addCardUrl":{"description":"Where the person adds or changes the card (website only).","type":"string"},"notes":{"description":"The setting in plain words.","type":"array","items":{"type":"string"}},"charged":{"description":"Switched on below the line: the first top-up, charged right away. null when nothing was charged.","anyOf":[{"type":"object","properties":{"amountUsd":{"type":"number"},"credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"balance":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["amountUsd","credits","balance"],"additionalProperties":false},{"type":"null"}]}},"required":["autoTopUp","balance","eligible","cardOnFile","addCardUrl","notes","charged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credits/history":{"get":{"operationId":"shared_credits_history","summary":"Your credit history: what was spent or added, newest first.","description":"Lists the credit changes on your account, newest first: videos and steps that spent credits, plan resets, purchases and refunds. Filter with type=debit (spent) or type=credit (added or refunded). Page with limit and next_cursor.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.credits.history","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_account action=credit_history","parameters":[{"name":"limit","in":"query","required":false,"schema":{"description":"How many items to return (1–100, default 20).","type":"integer","minimum":1,"maximum":100},"description":"How many items to return (1–100, default 20).","example":50},{"name":"cursor","in":"query","required":false,"schema":{"description":"The next_cursor from the previous page.","type":"string","maxLength":512},"description":"The next_cursor from the previous page."},{"name":"type","in":"query","required":false,"schema":{"description":"debit = spent, credit = added or refunded, all = both (default).","type":"string","enum":["debit","credit","all"]},"description":"debit = spent, credit = added or refunded, all = both (default).","example":"debit"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"description":"A stable id for this entry.","type":"string"},"date":{"description":"When it happened (ISO 8601, UTC).","type":"string"},"type":{"description":"debit = credits spent; credit = credits added or refunded.","type":"string","enum":["debit","credit"]},"amount":{"description":"How many credits. Always positive; `type` says which way.","type":"number"},"description":{"description":"What it was for, in plain words (no video provider names). A charge taken up front is shown as the charge it is; if part of it comes back later, that is its own entry.","type":"string"},"source":{"description":"What recorded it, for example a product or a billing event.","anyOf":[{"type":"string"},{"type":"null"}]},"feature":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditField":{"description":"Which balance it changed.","anyOf":[{"type":"string","enum":["v2credits","videoCredits"]},{"type":"null"}]},"sessionId":{"description":"The project it belongs to, read from the charge record: its own project, the charge a refund gives back, or the Autopilot run that made a 3D Animated Studio charge. null when the record does not say: plan resets and purchases have none, and a 3D Animated Studio charge names its film only when Autopilot made it or it is a soundtrack (a step started in the app, or one at a time through the API, keeps no project in its record).","anyOf":[{"type":"string"},{"type":"null"}]},"videoId":{"anyOf":[{"type":"string"},{"type":"null"}]},"balanceAfter":{"description":"That balance right after this entry, when it was recorded.","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["id","date","type","amount","description","source","feature","creditField","sessionId","videoId","balanceAfter"],"additionalProperties":false}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"has_more":{"type":"boolean"}},"required":["items","next_cursor","has_more"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"items":[{"id":"txn_4f1c2a9b7d3e5f60718293a4","date":"2026-09-28T09:41:12.000Z","type":"debit","amount":150,"description":"V3 video: How volcanoes form","source":"credit-wallet","feature":null,"creditField":"v2credits","sessionId":"v3_8c1d2e3f","videoId":null,"balanceAfter":1850}],"next_cursor":null,"has_more":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/editor/import-video":{"post":{"operationId":"shared_editor_import_video","summary":"Bring one of your finished AutoClips videos into your media library, to edit it. Free; nothing is copied.","description":"Any finished video from My Videos (autoclips_videos list gives source and videoId) becomes a file of your media library, measured on our servers. Put it on a project with autoclips_timeline edit (add_media with its mediaId), or start a project with it directly (create with { source, videoId }). Bringing the same video in again gives the same file.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.editor.import_video","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_editor action=import_video","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"description":"The kind of finished video (source from autoclips_videos list).","type":"string","enum":["faceless","character","studio","studio-v2","cinematic","quiz","text-story","talking-objects","fruit-stories","time-travel","claymation","miniature","stickman","ugc-ads","upscaler","editor"]},"videoId":{"description":"The video's id within its kind (videoId from autoclips_videos list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_.:-]+$"}},"required":["source","videoId"],"additionalProperties":false},"example":{"source":"character","videoId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"media":{"type":"object","properties":{"id":{"description":"The media id. Other tools take it as mediaId.","type":"string"},"type":{"description":"image, video or audio.","type":"string","enum":["image","video","audio"]},"mimeType":{"description":"The real file type, detected from the file itself.","anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"size":{"description":"Size in bytes.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"url":{"description":"Where the file is stored. Works in AutoClips projects.","type":"string"},"projectId":{"description":"The project it was uploaded for, if any.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"upload = someone uploaded it; ai = AutoClips generated it; library = one of your finished AutoClips videos, brought in for the Video Editor (autoclips_editor import_video).","type":"string","enum":["upload","ai","library"]}},"required":["id","type","mimeType","name","size","url","projectId","createdAt","source"],"additionalProperties":false},"durationMs":{"description":"How long the video plays.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["media","durationMs","width","height"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/editor/projects":{"post":{"operationId":"shared_editor_create","summary":"Start a Video Editor project: blank, or with your own videos and pictures as its first clips. Free.","description":"The website's Video Editor: a project anyone starts themselves, to edit any video they have. Leave items out for a blank project, or give up to 20 clips in order: { mediaId } for a file of your media library (upload one first with autoclips_media), or { source, videoId } for one of your finished videos (autoclips_videos list). Each video comes in whole, up to 10 minutes per clip; pictures stay 4 seconds. The frame follows the first video unless you set aspect. Then edit it with autoclips_timeline (product editor, this projectId) and make the video with export.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.editor.create","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_editor action=create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"The project's name, up to 120 characters. Default: the first clip's file name, or \"Untitled video\".","type":"string","minLength":1,"maxLength":120},"aspect":{"description":"The frame: 9:16 (tall), 16:9 (wide) or 1:1 (square). Default: the first video's own shape, or 9:16.","type":"string","enum":["9:16","16:9","1:1"]},"items":{"description":"Up to 20 clips to start with, in order. Leave it out for a blank project.","maxItems":20,"type":"array","items":{"description":"One clip to start with: { mediaId } for a file of your media library, or { source, videoId } for one of your finished videos.","type":"object","properties":{"mediaId":{"description":"A video or picture of your media library (autoclips_media list, upload or upload_link).","type":"string","pattern":"^[a-fA-F0-9]{24}$"},"source":{"description":"The kind of finished video (source from autoclips_videos list).","type":"string","enum":["faceless","character","studio","studio-v2","cinematic","quiz","text-story","talking-objects","fruit-stories","time-travel","claymation","miniature","stickman","ugc-ads","upscaler","editor"]},"videoId":{"description":"The video's id within its kind (videoId from autoclips_videos list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_.:-]+$"}},"additionalProperties":false}}},"additionalProperties":false},"example":{"title":"Beach day","aspect":"9:16"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"projectId":{"description":"The project id (edit_…). autoclips_timeline takes it with product editor.","type":"string"},"title":{"type":"string"},"aspect":{"description":"The frame: 9:16 (tall), 16:9 (wide) or 1:1 (square).","type":"string"},"durationMs":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"duration":{"description":"How long the timeline plays, like 1:05.","type":"string"},"scenes":{"description":"Clips on the video row.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"export":{"type":"object","properties":{"status":{"description":"idle, queued, rendering, finishing, completed, failed or cancelled.","type":"string"},"progress":{"type":"number"},"running":{"type":"boolean"},"videoUrl":{"description":"The last exported video, once one has finished.","anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"failed":{"description":"True when the last export failed (its credits were given back).","type":"boolean"}},"required":["status","progress","running","videoUrl","finishedAt","failed"],"additionalProperties":false},"links":{"type":"object","properties":{"editor":{"description":"The project in the website editor.","type":"string"}},"required":["editor"],"additionalProperties":false}},"required":["projectId","title","aspect","durationMs","duration","scenes","posterUrl","createdAt","updatedAt","export","links"],"additionalProperties":false},"tooLong":{"description":"True when the clips together play longer than an export can be (10:00): trim before exporting.","type":"boolean"}},"required":["project","tooLong"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"projectId":"edit_mh7k2x9a3f5e1b2c4d6a","title":"Beach day","aspect":"9:16","durationMs":42000,"duration":"0:42","scenes":3,"posterUrl":"https://media.autoclips.app/uploads/beach-day-poster.jpg","createdAt":"2026-10-26T09:00:00.000Z","updatedAt":"2026-10-26T09:12:00.000Z","export":{"status":"idle","progress":0,"running":false,"videoUrl":null,"finishedAt":null,"failed":false},"links":{"editor":"https://app.autoclips.app/editor/edit_mh7k2x9a3f5e1b2c4d6a"}},"tooLong":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"shared_editor_list","summary":"List your Video Editor projects, most recently changed first.","description":"Your Video Editor projects with their length, frame and last export, most recently changed first. Ask for the next page with before set to nextBefore.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.editor.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_editor action=list","parameters":[{"name":"limit","in":"query","required":false,"schema":{"description":"Projects per page (default 24).","type":"integer","minimum":1,"maximum":60},"description":"Projects per page (default 24)."},{"name":"before","in":"query","required":false,"schema":{"description":"nextBefore from the previous page.","type":"string","maxLength":40},"description":"nextBefore from the previous page."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"projectId":{"description":"The project id (edit_…). autoclips_timeline takes it with product editor.","type":"string"},"title":{"type":"string"},"aspect":{"description":"The frame: 9:16 (tall), 16:9 (wide) or 1:1 (square).","type":"string"},"durationMs":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"duration":{"description":"How long the timeline plays, like 1:05.","type":"string"},"scenes":{"description":"Clips on the video row.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"export":{"type":"object","properties":{"status":{"description":"idle, queued, rendering, finishing, completed, failed or cancelled.","type":"string"},"progress":{"type":"number"},"running":{"type":"boolean"},"videoUrl":{"description":"The last exported video, once one has finished.","anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"failed":{"description":"True when the last export failed (its credits were given back).","type":"boolean"}},"required":["status","progress","running","videoUrl","finishedAt","failed"],"additionalProperties":false},"links":{"type":"object","properties":{"editor":{"description":"The project in the website editor.","type":"string"}},"required":["editor"],"additionalProperties":false}},"required":["projectId","title","aspect","durationMs","duration","scenes","posterUrl","createdAt","updatedAt","export","links"],"additionalProperties":false}},"hasMore":{"type":"boolean"},"nextBefore":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["projects","hasMore","nextBefore"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"projects":[{"projectId":"edit_mh7k2x9a3f5e1b2c4d6a","title":"Beach day","aspect":"9:16","durationMs":42000,"duration":"0:42","scenes":3,"posterUrl":"https://media.autoclips.app/uploads/beach-day-poster.jpg","createdAt":"2026-10-26T09:00:00.000Z","updatedAt":"2026-10-26T09:12:00.000Z","export":{"status":"idle","progress":0,"running":false,"videoUrl":null,"finishedAt":null,"failed":false},"links":{"editor":"https://app.autoclips.app/editor/edit_mh7k2x9a3f5e1b2c4d6a"}}],"hasMore":false,"nextBefore":null}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/editor/projects/{projectId}":{"get":{"operationId":"shared_editor_get","summary":"One Video Editor project: its name, length, frame and last export. Its timeline is autoclips_timeline get (product editor).","description":"One Video Editor project: its name, length, frame and last export. Its timeline is autoclips_timeline get (product editor).\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.editor.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_editor action=get","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id (edit_…), from create or list. autoclips_timeline takes it as projectId with product editor.","type":"string","pattern":"^edit_[a-z0-9]{8,40}$"},"description":"The project id (edit_…), from create or list. autoclips_timeline takes it as projectId with product editor.","example":"edit_mh7k2x9a3f5e1b2c4d6a"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"projectId":{"description":"The project id (edit_…). autoclips_timeline takes it with product editor.","type":"string"},"title":{"type":"string"},"aspect":{"description":"The frame: 9:16 (tall), 16:9 (wide) or 1:1 (square).","type":"string"},"durationMs":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"duration":{"description":"How long the timeline plays, like 1:05.","type":"string"},"scenes":{"description":"Clips on the video row.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"export":{"type":"object","properties":{"status":{"description":"idle, queued, rendering, finishing, completed, failed or cancelled.","type":"string"},"progress":{"type":"number"},"running":{"type":"boolean"},"videoUrl":{"description":"The last exported video, once one has finished.","anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"failed":{"description":"True when the last export failed (its credits were given back).","type":"boolean"}},"required":["status","progress","running","videoUrl","finishedAt","failed"],"additionalProperties":false},"links":{"type":"object","properties":{"editor":{"description":"The project in the website editor.","type":"string"}},"required":["editor"],"additionalProperties":false}},"required":["projectId","title","aspect","durationMs","duration","scenes","posterUrl","createdAt","updatedAt","export","links"],"additionalProperties":false}},"required":["project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"project":{"projectId":"edit_mh7k2x9a3f5e1b2c4d6a","title":"Beach day","aspect":"9:16","durationMs":42000,"duration":"0:42","scenes":3,"posterUrl":"https://media.autoclips.app/uploads/beach-day-poster.jpg","createdAt":"2026-10-26T09:00:00.000Z","updatedAt":"2026-10-26T09:12:00.000Z","export":{"status":"idle","progress":0,"running":false,"videoUrl":null,"finishedAt":null,"failed":false},"links":{"editor":"https://app.autoclips.app/editor/edit_mh7k2x9a3f5e1b2c4d6a"}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"shared_editor_rename","summary":"Give a Video Editor project a new name.","description":"Give a Video Editor project a new name.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.editor.rename","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_editor action=rename","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"The project's name, up to 120 characters.","type":"string","minLength":1,"maxLength":120}},"required":["title"],"additionalProperties":false},"example":{"title":"Beach day, final"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id (edit_…), from create or list. autoclips_timeline takes it as projectId with product editor.","type":"string","pattern":"^edit_[a-z0-9]{8,40}$"},"description":"The project id (edit_…), from create or list. autoclips_timeline takes it as projectId with product editor.","example":"edit_mh7k2x9a3f5e1b2c4d6a"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"projectId":{"description":"The project id (edit_…). autoclips_timeline takes it with product editor.","type":"string"},"title":{"type":"string"},"aspect":{"description":"The frame: 9:16 (tall), 16:9 (wide) or 1:1 (square).","type":"string"},"durationMs":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"duration":{"description":"How long the timeline plays, like 1:05.","type":"string"},"scenes":{"description":"Clips on the video row.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"export":{"type":"object","properties":{"status":{"description":"idle, queued, rendering, finishing, completed, failed or cancelled.","type":"string"},"progress":{"type":"number"},"running":{"type":"boolean"},"videoUrl":{"description":"The last exported video, once one has finished.","anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"failed":{"description":"True when the last export failed (its credits were given back).","type":"boolean"}},"required":["status","progress","running","videoUrl","finishedAt","failed"],"additionalProperties":false},"links":{"type":"object","properties":{"editor":{"description":"The project in the website editor.","type":"string"}},"required":["editor"],"additionalProperties":false}},"required":["projectId","title","aspect","durationMs","duration","scenes","posterUrl","createdAt","updatedAt","export","links"],"additionalProperties":false}},"required":["project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"shared_editor_delete","summary":"Delete a Video Editor project. It leaves the editor and My Videos; the files in your media library stay.","description":"Deletes the project and its timeline. Refused while it is exporting: stop the export first (autoclips_timeline render_cancel, product editor) or wait for it.\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["Account, media and publishing"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"shared.editor.delete","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_editor action=delete","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id (edit_…), from create or list. autoclips_timeline takes it as projectId with product editor.","type":"string","pattern":"^edit_[a-z0-9]{8,40}$"},"description":"The project id (edit_…), from create or list. autoclips_timeline takes it as projectId with product editor.","example":"edit_mh7k2x9a3f5e1b2c4d6a"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"},"projectId":{"type":"string"}},"required":["deleted","projectId"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"deleted":true,"projectId":"edit_mh7k2x9a3f5e1b2c4d6a"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/editor/projects/{projectId}/captions":{"post":{"operationId":"shared_editor_captions","summary":"Captions from what is said in the project's videos, timed to the speech, on every video scene (or the ones you pick).","description":"Like the editor's Caption all: every video scene on the video row (or the scenes in clipIds), one after another, and one undo step for all of them. Captions are switched on for the video if they were off, each scene's own sound is switched on so the words are heard, and the caption language follows the language heard unless someone chose one. Each video file is listened to whole, once, at about 4 credits a minute of file; every scene cut from a file heard before is captioned from those words at no charge, and a file without sound costs nothing. A failed listen gives its credits back. Send expectedRevision from autoclips_timeline get. Up to 60 scenes and 10 new files a call; files up to 30 minutes long.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"shared.editor.captions","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"autoclips_editor action=captions","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedRevision":{"description":"The revision you read with get (or got back from your last edit). If the timeline changed since, nothing is saved and the answer is revision_conflict: read it again and redo the edit.","type":"integer","minimum":0,"maximum":1000000000},"clipIds":{"description":"The video scenes to caption (clip ids on the video row, from autoclips_timeline get). Leave it out for every video scene.","minItems":1,"maxItems":60,"type":"array","items":{"description":"A video scene's clip id, from autoclips_timeline get.","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"}},"language":{"description":"The language spoken, as a code like en, es, hi (or auto). Leave it out to detect it in each file.","type":"string","pattern":"^(auto|[a-z]{2,3})$"},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"required":["expectedRevision"],"additionalProperties":false},"example":{"expectedRevision":7}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id (edit_…), from create or list. autoclips_timeline takes it as projectId with product editor.","type":"string","pattern":"^edit_[a-z0-9]{8,40}$"},"description":"The project id (edit_…), from create or list. autoclips_timeline takes it as projectId with product editor.","example":"edit_mh7k2x9a3f5e1b2c4d6a"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"revision":{"description":"The timeline's revision now. Use it as expectedRevision next time.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"saved":{"type":"boolean"},"changes":{"description":"What changed, in plain words.","type":"array","items":{"type":"string"}},"warnings":{"description":"Things the downloaded video cannot show, if any.","type":"array","items":{"type":"string"}},"undo":{"description":"Whether undo can take a change back, and how many kept versions it can go back through.","type":"object","properties":{"available":{"type":"boolean"},"versions":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["available","versions"],"additionalProperties":false},"redo":{"description":"Whether redo can put back what an undo took away. A new edit clears it.","type":"object","properties":{"available":{"type":"boolean"},"versions":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["available","versions"],"additionalProperties":false},"skipped":{"description":"Undo or redo only: kept versions that could not be put back (their media left your library, say), so they were removed and the next one was used.","type":"array","items":{"type":"object","properties":{"revision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reason":{"type":"string"}},"required":["revision","reason"],"additionalProperties":false}},"timeline":{"type":"object","properties":{"product":{"type":"string","enum":["v3","studio","editor"]},"projectId":{"type":"string"},"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"cuts":{"description":"Studio 2.0: every cut of the project that opens in the editor.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"hasEdits":{"type":"boolean"}},"required":["id","label","hasEdits"],"additionalProperties":false}},"revision":{"description":"Send this as expectedRevision with your next edit.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasSavedEdits":{"type":"boolean"},"title":{"type":"string"},"aspect":{"type":"string"},"durationMs":{"type":"number"},"duration":{"type":"string"},"videoSpeed":{"type":"number"},"tracks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"clips":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"muted":{"type":"boolean"},"hidden":{"type":"boolean"},"locked":{"type":"boolean"}},"required":["id","label","kind","clips"],"additionalProperties":false}},"clips":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"track":{"description":"video, overlay, studio_text, text, sound_effects, audio or music.","type":"string"},"kind":{"description":"image, video, text, studio-text or audio.","type":"string"},"scene":{"description":"Scenes only: its number, counting from 1.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"startMs":{"type":"number"},"endMs":{"type":"number"},"time":{"description":"The same times as \"0:03-0:07\".","type":"string"},"label":{"type":"string"},"text":{"type":"string"},"caption":{"description":"Scenes only: the words spoken in it.","type":"string"},"captionsOff":{"type":"boolean"},"media":{"type":"object","properties":{"kind":{"type":"string"},"url":{"type":"string"}},"required":["kind","url"],"additionalProperties":false},"transitionIn":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"durationMs":{"type":"number"}},"required":["type","name","durationMs"],"additionalProperties":false},"sound":{"description":"What set_clip_sound can change, as it is now.","type":"object","properties":{"on":{"type":"boolean"},"volumeDb":{"description":"Volume in dB, 0 as recorded. On music that dips under the narrator's words, the level between the lines (underVoiceDb is the level under them).","type":"number"},"fadeInMs":{"type":"number"},"fadeOutMs":{"type":"number"},"dipUnderVoice":{"description":"Music only: it really is lowered while the narrator speaks, as the video plays it. False when its dip is off, on a video with no narrator, and on older V3 music (made before 2026-10-05) that does not follow the narrator's words: that plays at a steady volumeDb under the voice, though the editor shows its dip switched on, and its note says so.","type":"boolean"},"dipUnderClipSound":{"description":"Music only: it is also lowered under talking recorded in the videos.","type":"boolean"},"dipDb":{"description":"Music only: how far it dips (dB), when it dips.","type":"number"},"underVoiceDb":{"description":"Music that dips under the narrator only: its level under the voice (volumeDb + dipDb).","type":"number"},"note":{"description":"Older music that plays at a steady level under the narrator says so here, and how to make it dip.","type":"string"}},"required":["on","volumeDb","fadeInMs","fadeOutMs"],"additionalProperties":false},"visibleArea":{"description":"Scenes only, when reframe moved it off the middle: which part of the picture shows where it is not the frame's shape.","type":"object","properties":{"x":{"description":"0 left edge, 50 middle, 100 right edge.","type":"number"},"y":{"description":"0 top, 50 middle, 100 bottom.","type":"number"}},"required":["x","y"],"additionalProperties":false},"sfxId":{"type":"string"},"musicId":{"description":"Music only: the track it came from (an id from the music action).","type":"string"},"warning":{"description":"A popular song: AutoClips does not license it.","type":"string"},"studio":{"description":"Studio 2.0 texts only: what set_studio_text_style can change, as it is now.","type":"object","properties":{"kind":{"description":"title, message (a chat bubble), label (a pill) or end_card.","type":"string","enum":["title","end_card","message","label"]},"words":{"description":"Its words, counting from 0: what wordColors in set_studio_text_style points at.","type":"array","items":{"type":"string"}},"side":{"description":"A chat message only: incoming (sent by them, left) or outgoing (sent by me, right).","type":"string","enum":["incoming","outgoing"]},"sender":{"description":"A chat message only: its name. The video shows the name only on a bubble sent by them. A bubble sent by me keeps the name it had, but the video shows none (its note says so). \"\" is no name.","type":"string"},"note":{"description":"A chat bubble sent by me that kept a name: says the video does not show that name.","type":"string"},"look":{"type":"object","properties":{"font":{"type":"string"},"color":{"type":"string"},"background":{"type":"string"},"size":{"description":"Percent of the kind's usual size.","type":"number"},"x":{"description":"Percent across the frame; null is its usual place.","anyOf":[{"type":"number"},{"type":"null"}]},"y":{"description":"Percent down the frame; null is its usual place.","anyOf":[{"type":"number"},{"type":"null"}]},"icon":{"type":"boolean"},"wordColors":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"color":{"type":"string"}},"required":["index","color"],"additionalProperties":false}},"custom":{"description":"True when anything differs from the kind's default look.","type":"boolean"}},"required":["font","color","size","x","y","wordColors","custom"],"additionalProperties":false}},"required":["kind","words","look"],"additionalProperties":false},"hidden":{"type":"boolean"},"locked":{"type":"boolean"}},"required":["id","track","kind","startMs","endMs","time","label"],"additionalProperties":false}},"clipsShown":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clipsTotal":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"trimmed":{"anyOf":[{"type":"string"},{"type":"null"}]},"captions":{"type":"object","properties":{"enabled":{"type":"boolean"},"style":{"type":"string"},"font":{"type":"string"},"position":{"type":"string"},"size":{"type":"number"},"color":{"type":"string"},"highlightColor":{"type":"string"},"background":{"type":"boolean"},"wordsOnScreen":{"type":"number"},"scenesWithWords":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"scenesOff":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["enabled","style","font","position","size","color","highlightColor","background","wordsOnScreen","scenesWithWords","scenesOff"],"additionalProperties":false},"markers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"atMs":{"type":"number"},"at":{"type":"string"},"label":{"type":"string"}},"required":["id","atMs","at","label"],"additionalProperties":false}},"render":{"anyOf":[{"type":"object","properties":{"status":{"description":"idle, queued, rendering, finishing, completed, failed or cancelled.","type":"string"},"progress":{"type":"number"},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"description":"The finished video, once completed.","anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"canCancel":{"type":"boolean"},"stale":{"description":"True when the render stopped reporting for a while; asking again re-checks it with the render service.","type":"boolean"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastVideo":{"description":"The last video the editor finished, and which revision it was made from.","anyOf":[{"type":"object","properties":{"videoUrl":{"type":"string"},"revision":{"anyOf":[{"type":"number"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["videoUrl","revision","finishedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["status","progress","stage","videoUrl","error","canCancel","stale","startedAt","lastVideo"],"additionalProperties":false},{"type":"null"}]},"links":{"type":"object","properties":{"editor":{"type":"string"}},"required":["editor"],"additionalProperties":false}},"required":["product","projectId","variantId","revision","hasSavedEdits","title","aspect","durationMs","duration","videoSpeed","tracks","clips","clipsShown","clipsTotal","trimmed","captions","markers","render","links"],"additionalProperties":false},"clips":{"description":"What happened to each scene, in timeline order.","type":"array","items":{"type":"object","properties":{"clipId":{"type":"string"},"scene":{"description":"The scene's number, counting from 1.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"status":{"description":"ready: captions added. no_speech: nobody speaks in it. failed: see error. skipped: not tried (the balance ran out on an earlier scene).","type":"string","enum":["ready","no_speech","failed","skipped"]},"words":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"language":{"description":"The language heard (a code like en).","anyOf":[{"type":"string"},{"type":"null"}]},"text":{"description":"What was said, as heard (shortened).","type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["clipId","scene","status","words","language","text","error"],"additionalProperties":false}},"creditsCharged":{"description":"What listening charged: 0 when every file was heard before or has no sound.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["revision","variantId","saved","changes","warnings","undo","timeline","clips","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/editor/projects/{projectId}/export":{"post":{"operationId":"shared_editor_export","summary":"Make the video from the project as it is saved now, like the editor's Export button. Answers with a job to follow.","description":"Renders the saved timeline into an MP4 and answers at once with a job: follow it with autoclips_jobs get (GET /jobs/{id}); when it succeeds its result has videoUrl. The price follows how long the video plays: 13 credits for 30 seconds, 17 for a minute, 75 for 10 minutes, the longest an export can be. A failed or cancelled export gives its credits back. Stop one with autoclips_timeline render_cancel (product editor). One export per project at a time, and up to 2 of your projects at once.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"shared.editor.export","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"autoclips_editor action=export","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id (edit_…), from create or list. autoclips_timeline takes it as projectId with product editor.","type":"string","pattern":"^edit_[a-z0-9]{8,40}$"},"description":"The project id (edit_…), from create or list. autoclips_timeline takes it as projectId with product editor.","example":"edit_mh7k2x9a3f5e1b2c4d6a"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"alreadyRunning":{"description":"True when this project was already exporting: the answer is that export's job, and nothing was charged.","type":"boolean"},"revision":{"description":"The timeline revision being exported.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"render":{"anyOf":[{"type":"object","properties":{"status":{"description":"idle, queued, rendering, finishing, completed, failed or cancelled.","type":"string"},"progress":{"type":"number"},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"description":"The finished video, once completed.","anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"canCancel":{"type":"boolean"},"stale":{"description":"True when the render stopped reporting for a while; asking again re-checks it with the render service.","type":"boolean"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastVideo":{"description":"The last video the editor finished, and which revision it was made from.","anyOf":[{"type":"object","properties":{"videoUrl":{"type":"string"},"revision":{"anyOf":[{"type":"number"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["videoUrl","revision","finishedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["status","progress","stage","videoUrl","error","canCancel","stale","startedAt","lastVideo"],"additionalProperties":false},{"type":"null"}]},"creditsCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"warnings":{"description":"Edits the video cannot show, if any.","type":"array","items":{"type":"string"}}},"required":["job","alreadyRunning","revision","render","creditsCharged","warnings"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"job":{"id":"job_0192f1a2b3c4d5e6f7a8b9c2","product":"shared","kind":"shared.editor_export","resource":{"type":"project","id":"edit_mh7k2x9a3f5e1b2c4d6a"},"status":"queued","step":"waiting for the render service","progress":0,"result":null,"error":null,"createdAt":"2026-10-26T09:15:00.000Z","updatedAt":"2026-10-26T09:15:00.000Z","finishedAt":null,"poll_after_seconds":15},"alreadyRunning":false,"revision":7,"render":{"status":"queued","progress":0,"stage":"submit","videoUrl":null,"error":null,"canCancel":true,"stale":false,"startedAt":"2026-10-26T09:15:00.000Z","lastVideo":null},"creditsCharged":13,"warnings":[]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/automations":{"get":{"operationId":"fruit_automations_list","summary":"List your Fruit and Animal story automations with their settings, series, schedule and daily limit.","description":"List your Fruit and Animal story automations with their settings, series, schedule and daily limit.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"fruit.automations.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_automations action=list","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automations":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"story":{"description":"Every story setting, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"series":{"type":"object","properties":{"enabled":{"type":"boolean"},"parts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"afterLastPart":{"type":"string","enum":["new_series","stop"]},"current":{"description":"The series being told now, and how many parts are posted.","anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partsMade":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["seriesId","title","partsMade"],"additionalProperties":false},{"type":"null"}]}},"required":["enabled","parts","afterLastPart","current"],"additionalProperties":false},"ideas":{"type":"object","properties":{"ideas":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ideas"],"additionalProperties":false},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","status","pauseReason","schedule","story","series","ideas","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false}}},"required":["automations"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"automations":[{"id":"7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d","name":"Fruit Drama Daily","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["18:00"],"videosPerDay":1},"story":{"species":"fruit","storyFormat":"forehead-number","formatAuto":false,"lengthSeconds":75,"language":"en","aspectRatio":"9:16","chemistry":"flirty","look":null,"scriptModel":"opus","imageModel":"nano-banana-2","videoModel":"autoclips1","captions":true,"music":"default","narrationMode":"spoken","videoSpeed":1,"partLabel":true,"characterIds":[]},"series":{"enabled":true,"parts":5,"afterLastPart":"new_series","current":null},"ideas":{"ideas":"Rich vs poor revenge stories with a twist"},"publishing":{"email":true,"library":true,"tiktok":{"enabled":true,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":5200,"approvedAt":"2026-10-27T09:00:00.000Z"},"estimatedCreditsPerRun":5200,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-10-27T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"fruit_automations_create","summary":"Set up an automation that makes and posts Fruit or Animal stories on a schedule, one a run or as a series, within a daily limit.","description":"Makes a Fruit AI / Animal Stories automation with every option of the create page (story: species, format or best fit, look, chemistry, length, language, shape, writer, picture and video models, captions, music, Short Film voices, speed, PART label, library characters). At each posting time it writes a new story idea from your ideas and makes the whole story (script, cast, frames, clips, render), then posts it with its cover and post text. With series on, Part 1 comes first and each run makes the next part from the last part's cliffhanger with the same characters; the last part closes the story. Each story is charged step by step, as on the page, and what does not come out is refunded; a story stops before a step that would pass its most. What you approve is a daily spending limit (spendLimitPerDay; left out, one day of runs at their most): a run that would pass it is skipped until the next day, and a run is settled after it is made, so one step's final cost can run a little over. Posting needs the publish permission and your own accounts. Writing its first ideas counts toward the free-AI daily limit.\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. Fruit automation day stops before a step that would go past the limit, but one step's final cost can run a little over, so the limit is not the most it can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.automations.create","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_automations action=create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The automation's name: unique on your account, at most 100 characters.","type":"string","minLength":1,"maxLength":100},"schedule":{"description":"When it runs. A new automation needs all three; an update changes only what you send.","type":"object","properties":{"timezone":{"description":"The time zone of the posting times (IANA, for example \"America/New_York\").","type":"string","minLength":1,"maxLength":64},"videosPerDay":{"description":"Videos a day, 1 to 3: one per posting time.","type":"integer","minimum":1,"maximum":3},"times":{"description":"The posting times, one per video a day (\"09:00\", 24-hour).","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}}},"additionalProperties":false},"story":{"description":"Every option of the Fruit create page, for each run's story (autoclips_options product fruit). Left out on a create: a 75-second Fruit story in the Number on Forehead format.","type":"object","properties":{"species":{"description":"Fruit or animal: Fruit AI (people with fruit heads) or Animal Stories (photoreal animal heads on people). Animal Stories come only in the story formats, take an idea (not a pasted script) and do not use the fruit character library.\nChoices:\n- fruit — Fruit AI: Fruit-headed people, every format.\n- animal — Animal Stories: Animal-headed people, story formats only.\nDefault: fruit.","type":"string","enum":["fruit","animal"]},"storyFormat":{"description":"Format: The shape of the story. Story formats (65 to 85 seconds, Pro and up) are viral micro-dramas with a world rule and a Part 2 hook; reel formats are the measured 30 to 65 second Fruit comedies; the older formats are kept for those who use them. Animal Stories take a story format only (default secret-identity). fruit_formats get shows a format's example video, beats and default look.\nChoices:\n- forehead-number — Number on Forehead: Story format: Everyone can see your number. Then it changes. (plans: pro, advanced, enterprise, ultra, legacy)\n- million-challenge — Million-Dollar Challenge: Story format: Your worst habit just became worth a million. (plans: pro, advanced, enterprise, ultra, legacy)\n- secret-identity — Secret Identity: Story format: The new kid is quiet. Nobody knows who he really is. (plans: pro, advanced, enterprise, ultra, legacy)\n- plot-twist — Emotional Plot Twist: Story format: A wrong done in plain sight. A twist nobody saw coming. (plans: pro, advanced, enterprise, ultra, legacy)\n- glow-up — Glow-Up Revenge: Story format: They called her a zero. Wait till they see her now. (plans: pro, advanced, enterprise, ultra, legacy)\n- giant-curse — Giant Curse: Story format: One spell made her enormous. Now he has to break it. (plans: pro, advanced, enterprise, ultra, legacy)\n- impossible-commission — Impossible Commission: Story format: A billionaire problem. A $5 builder. One shot. (plans: pro, advanced, enterprise, ultra, legacy)\n- countdown-trap — Countdown Trap: Story format: Ten seconds left. And someone planned this. (plans: pro, advanced, enterprise, ultra, legacy)\n- the-test — The Test: Story format: Two heirs. Three suitors. Only one passes. (plans: pro, advanced, enterprise, ultra, legacy)\n- burger-money — Rich vs Poor: Reel format: The rich one mocks the worker. Then needs them.\n- cheating — Cheating: Reel format: Caught in the act. One lie. One cold verdict.\n- cuh — Cuh: Reel format: Dad picks a favourite. Years later the other one wins.\n- correct-me — Correct Me If I'm Wrong: Reel format: He asks the wrong question. It works anyway.\n- two-paths — Two Child, Two Paths: Reel format: Two babies, two trades, one couch.\n- custom — Custom: Reel format: Your idea or your script, told your way.\n- short-film — Short Film: Classic format: Cinematic mini-movie — widescreen, real camera work. (plans: pro, advanced, enterprise, ultra, legacy)\n- reality-show — Reality Show: Classic format: Love Island style dating drama.\n- comedy — Comedy Sketch: Classic format: Short-form comedy. (plans: pro, advanced, enterprise, ultra, legacy)\n- drama — Drama Series: Classic format: Serialized dramatic storytelling. (plans: pro, advanced, enterprise, ultra, legacy)\n- educational — Educational: Classic format: Fun educational content. (plans: pro, advanced, enterprise, ultra, legacy)\n- music-video — Music Video: Classic format: Performance and dance. (plans: pro, advanced, enterprise, ultra, legacy)\n- cooking-show — Cooking Show: Classic format: Food-related scenarios. (plans: pro, advanced, enterprise, ultra, legacy)\nDefault: forehead-number.","type":"string","enum":["forehead-number","million-challenge","secret-identity","plot-twist","glow-up","giant-curse","impossible-commission","countdown-trap","the-test","burger-money","cheating","cuh","correct-me","two-paths","custom","short-film","reality-show","comedy","drama","educational","music-video","cooking-show"]},"formatAuto":{"description":"Story formats only: the director picks the story format that fits the idea best (storyFormat is the fallback). Default false.","type":"boolean"},"lengthSeconds":{"description":"How long it runs, in seconds: a story format 65, 75 or 85; any other format 30, 38, 46, 54, 60 or 65. Default: the format's own (75 or 46). Over 32 seconds needs Pro or higher.","type":"integer","minimum":20,"maximum":90},"language":{"description":"The language the characters speak (autoclips_options product fruit, option language). Default en.","type":"string","minLength":2,"maxLength":16},"aspectRatio":{"description":"Shape: The video's shape. A series keeps the shape of its Part 1.\nChoices:\n- 9:16 — 9:16: Vertical (TikTok/Reels).\n- 16:9 — 16:9: Horizontal (YouTube).\n- 1:1 — 1:1: Square.\nDefault: 9:16.","type":"string","enum":["9:16","16:9","1:1"]},"chemistry":{"description":"Chemistry: How much romance the couples show. Clothes stay on at every level.\nChoices:\n- clean — Clean: Barely touch. The story is the same.\n- flirty — Flirty: Hugs, an arm round a waist, looks that hold.\n- spicy — Spicy: Kissing and dancing too. Adds a dance track.\nDefault: flirty.","type":"string","enum":["clean","flirty","spicy"]},"look":{"description":"Look: How the cast is dressed. Left out, the format decides (Hot on glow-up, giant-curse and impossible-commission; Classic elsewhere), and an idea about a child or a teenager is always Classic by default. Hot is grown-ups (21+) only and never nudity. A series keeps its look unless a part picks one.\nChoices:\n- classic — Classic: Everyone dressed for the story.\n- hot — Hot: Glamorous grown-up leads: figure-hugging outfits, curves, cleavage. Never nudity.\nDefault: The format's own look (leave it out).","type":"string","enum":["classic","hot"]},"scriptModel":{"description":"Writer: Which AI writes the script. The writer sets the script's price.\nChoices:\n- opus — Claude Opus 5.5: Claude Opus 5.5 writes the script. (300 credits for the script)\n- gemini — Gemini 3.8 Flash: Gemini 3.8 Flash writes the script. (120 credits for the script)\n- muse — Muse Spark 1.3: Muse Spark 1.3 writes the script. (120 credits for the script)\n- kimi — Kimi K3: Kimi K3 writes the script. (200 credits for the script)\n- grok — Grok 4.6: Grok 4.6 writes the script. (110 credits for the script)\nDefault: opus.","type":"string","enum":["opus","gemini","muse","kimi","grok"]},"imageModel":{"description":"Picture model: Which model draws the character looks and the scene frames. It sets each picture's price.\nChoices:\n- nano-banana-2 — Nano Banana 2: Highest quality, best character consistency. (72 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2-high — Precision Max: Sharpest detail and the most literal prompt accuracy. (107 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2 — Precision: Same accuracy at a lower resolution — cheaper per image. (33 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-2-pro — FLUX 2 Pro: Excellent style adherence and detail. (48 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- nano-banana — Nano Banana: Good quality, faster generation. (24 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-kontext-pro — FLUX Kontext Pro: Good balance of quality and speed. (24 credits a picture)\n- flux-kontext-dev — FLUX Kontext Dev: Budget option for testing. (15 credits a picture)\n- krea-2-medium — Krea 2: Stunning aesthetics — style-reference consistency. (25 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\nDefault: nano-banana-2.","type":"string","enum":["nano-banana-2","gpt-image-2-high","gpt-image-2","flux-2-pro","nano-banana","flux-kontext-pro","flux-kontext-dev","krea-2-medium"]},"videoModel":{"description":"Video model: Which model films each scene's talking clip. The four AutoClips models and Reel are on the create page. AutoClips 1 Lite and Lite Full HD speak the lines in each character's voice (set it with the cast's voice option; voices are free). A Short Film is filmed on Cinematic Pro; the others are kept for older stories.\nChoices:\n- autoclips1 — AutoClips 1: Our main model. Strong acting, speaks every line. (12 credits a second of clip)\n- autoclips1Upscaled — AutoClips 1 1080p Upscaled: AutoClips 1, sharpened to 1080p. (16 credits a second of clip)\n- autoclips1Light — AutoClips 1 Lite: Half the price. Lines are spoken in the voices you pick. (6 credits a second of clip)\n- autoclips1LightHd — AutoClips 1 Lite Full HD: AutoClips 1 Lite drawn at full 1080p. (18 credits a second of clip)\n- autoclips — AutoClips 1 1080p Upscaled: The older name for AutoClips 1 1080p Upscaled, kept for saved stories and automations. (16 credits a second of clip)\n- minimax — Reel: Big expressive acting, one clean shot per scene, 10-second clips. (52 credits a second of clip)\n- omniMax — Pro Max: Best quality, fastest generation. (1500 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\n- veo31lite — Lite: Fast and affordable — 720p with audio. (240 credits a clip)\n- klingStd — Cinematic: Multi-shot — several camera angles cut together in one take. (600 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\n- klingPro — Cinematic Pro: Multi-shot at the highest quality tier. (810 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\nDefault: autoclips1.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd","autoclips","minimax","omniMax","veo31lite","klingStd","klingPro"]},"captions":{"description":"Burned-in word-by-word captions. Default true (a silent Short Film has none).","type":"boolean"},"music":{"title":"Background music (Fruit AI Stories and Animal Stories option music)","description":"Background music: The music bed, as \"<shelf>:<track id>\" (fai, popular or v3) or \"none\". Left out: story formats start on a copyright-free sad bed; other formats start with no music.\nOne of 333 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=fruit&option=music) to see them all.\nChoices:\n- none — No music: The story plays with its voices and sound only.\n- fai:fai-batida-funk — Batida Funk: Fruit picks shelf.\n- fai:fai-popular — Popular: Fruit picks shelf.\n- fai:fai-slowed — Slowed: Fruit picks shelf.\n- fai:fai-normal — Normal: Fruit picks shelf.\n- popular:hide-and-sneak — Hide and Sneak: Popular shelf.\n- popular:old-time-circus — Old Time Circus: Popular shelf.\n- popular:lurking-behind — Lurking Behind: Popular shelf.\n- popular:ce-burning-memory — It's Just a Burning Memory: Popular shelf.\n- popular:ce-f-down — F.Down: Popular shelf.\n- popular:ce-school-rooftop — School Rooftop (Bird Sounds): Popular shelf.\n- popular:ce-promise-reprise — Promise (Reprise): Popular shelf.\n- popular:ce-everything-in-its-right-place — Everything In Its Right Place (Instrumental): Popular shelf.\n- popular:ce-six-forty-seven — Six Forty Seven: Popular shelf.\n- popular:ce-numbers — Numbers (Instrumental): Popular shelf.\n- popular:ce-fallen-down — Fallen Down (Panic Room): Popular shelf.\n- popular:ce-char-remix — Char (Remix) Slowed: Popular shelf.\n- popular:ce-empathy — Empathy (Slowed + Reverb): Popular shelf.\n- popular:ce-aleph — ALEPH (Slowed + Reverb): Popular shelf.\n- popular:ce-solitude — Solitude (Slowed): Popular shelf.\n- popular:ce-closed-slowed — Closed (Slowed + Reverb): Popular shelf.\n- popular:ce-silhouette — Silhouette (Slowed Best Part): Popular shelf.\n- popular:ce-country-roads — Take Me Home, Country Roads (Karaoke): Popular shelf.\n- popular:ce-house-rising-sun — The House Of The Rising Sun (Instrumental): Popular shelf.\n- popular:ce-feeling-blue — Feeling Blue: Popular shelf.\n- popular:ce-stargazing — Stargazing (Sped Up): Popular shelf.\n- v3:animals-wildlife-01-wild-kingdom-v1 — Wild Kingdom: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-01-wild-kingdom-v2 — Wild Kingdom: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-02-migration-path-v1 — Migration Path: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-02-migration-path-v2 — Migration Path: Copyright-free shelf, copyright-free.\n…and 303 more.\nDefault: The format's default bed (leave it out).","type":"string"},"narrationMode":{"description":"Spoken or silent (Short Film): Short Film only: spoken (dense dialogue) or silent (no dialogue at all, the story told in pictures). Every other format is spoken. A series keeps it.\nChoices:\n- spoken — Spoken: The characters talk.\n- silent — Silent: Nobody speaks; no captions.\nDefault: spoken.","type":"string","enum":["spoken","silent"]},"videoSpeed":{"description":"Speed: How fast the finished video plays, 1x to 2x in steps of 0.1. Changing it on a finished video needs a new render. Series parts keep the speed of the series unless a part picks one. From 1 to 2 x, in steps of 0.1. Default: 1.","type":"number","minimum":1,"maximum":2,"multipleOf":0.1},"partLabel":{"description":"Story formats: show the \"PART N\" label. Default true.","type":"boolean"},"characterIds":{"description":"Fruit AI only: up to 8 characters from your library (yours, a preset or a public one) to cast. Left out: the writer invents the whole cast.","maxItems":8,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$"}}},"additionalProperties":false},"series":{"type":"object","properties":{"enabled":{"description":"true: Part 1, then each run makes the next part from the last part's cliffhanger with the same characters. false: a new story every run.","type":"boolean"},"parts":{"description":"Parts in a series, 2 to 10; the last one closes the story.","type":"integer","minimum":2,"maximum":10},"afterLastPart":{"description":"After the last part: new_series (the next run starts a new series) or stop (the automation pauses).","type":"string","enum":["new_series","stop"]}},"additionalProperties":false},"ideas":{"type":"object","properties":{"ideas":{"description":"What the stories are about, in your words (\"rich vs poor revenge stories\", \"office romance with a twist\"). Every run gets a new idea written from it.","type":"string","minLength":1,"maxLength":2000}},"required":["ideas"],"additionalProperties":false},"publishing":{"description":"Where each video goes. Switching posting on, changing the posting account or making YouTube videos more public needs the publish permission; only the platforms you send change.","type":"object","properties":{"email":{"description":"Email you when each video is ready.","type":"boolean"},"library":{"description":"Keep each video in My Videos.","type":"boolean"},"tiktok":{"description":"Posting to TikTok.","type":"object","properties":{"enabled":{"description":"Post every video to TikTok.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"youtube":{"description":"Posting to YouTube.","type":"object","properties":{"enabled":{"description":"Post every video to YouTube.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"},"privacy":{"description":"public, unlisted or private (default private; private videos get no comments, so no votes).","type":"string","enum":["public","unlisted","private"]},"categoryId":{"description":"The YouTube category id (2 Autos & Vehicles, 23 Comedy, 27 Education, 24 Entertainment, 1 Film & Animation, 20 Gaming, 26 Howto & Style, 10 Music, 25 News & Politics, 29 Nonprofits & Activism, 22 People & Blogs, 15 Pets & Animals, 28 Science & Technology, 17 Sports, 19 Travel & Events).","type":"string","enum":["1","2","10","15","17","19","20","22","23","24","25","26","27","28","29"]},"useAIMetadata":{"description":"Write the title and description from the video (default true).","type":"boolean"}},"required":["enabled"],"additionalProperties":false},"instagram":{"description":"Posting to Instagram.","type":"object","properties":{"enabled":{"description":"Post every video to Instagram.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"facebook":{"description":"Posting to Facebook.","type":"object","properties":{"enabled":{"description":"Post every video to Facebook.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"twitter":{"description":"Posting to X.","type":"object","properties":{"enabled":{"description":"Post every video to X.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"snapchat":{"description":"Posting to Snapchat.","type":"object","properties":{"enabled":{"description":"Post every video to Snapchat.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false}},"additionalProperties":false},"spendLimitPerDay":{"description":"The most it may spend a day, in credits (1 to 100,000). Left out: one day of runs at their most.","type":"integer","minimum":1,"maximum":100000},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["name","schedule"],"additionalProperties":false},"example":{"name":"Fruit Drama Daily","schedule":{"timezone":"America/New_York","videosPerDay":1,"times":["18:00"]},"story":{"storyFormat":"forehead-number","lengthSeconds":75,"look":"classic"},"series":{"enabled":true,"parts":5,"afterLastPart":"new_series"},"ideas":{"ideas":"Rich vs poor revenge stories with a twist"},"publishing":{"tiktok":{"enabled":true}}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"story":{"description":"Every story setting, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"series":{"type":"object","properties":{"enabled":{"type":"boolean"},"parts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"afterLastPart":{"type":"string","enum":["new_series","stop"]},"current":{"description":"The series being told now, and how many parts are posted.","anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partsMade":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["seriesId","title","partsMade"],"additionalProperties":false},{"type":"null"}]}},"required":["enabled","parts","afterLastPart","current"],"additionalProperties":false},"ideas":{"type":"object","properties":{"ideas":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ideas"],"additionalProperties":false},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","status","pauseReason","schedule","story","series","ideas","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"approvedCreditsPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["automation","approvedCreditsPerDay"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d","name":"Fruit Drama Daily","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["18:00"],"videosPerDay":1},"story":{"species":"fruit","storyFormat":"forehead-number","formatAuto":false,"lengthSeconds":75,"language":"en","aspectRatio":"9:16","chemistry":"flirty","look":null,"scriptModel":"opus","imageModel":"nano-banana-2","videoModel":"autoclips1","captions":true,"music":"default","narrationMode":"spoken","videoSpeed":1,"partLabel":true,"characterIds":[]},"series":{"enabled":true,"parts":5,"afterLastPart":"new_series","current":null},"ideas":{"ideas":"Rich vs poor revenge stories with a twist"},"publishing":{"email":true,"library":true,"tiktok":{"enabled":true,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":5200,"approvedAt":"2026-10-27T09:00:00.000Z"},"estimatedCreditsPerRun":5200,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-10-27T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d"},"approvedCreditsPerDay":5200}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/automations/{automationId}":{"get":{"operationId":"fruit_automations_get","summary":"Read one Fruit automation: its settings, series, schedule and recent runs.","description":"Read one Fruit automation: its settings, series, schedule and recent runs.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"fruit.automations.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_automations action=get","parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120},"description":"The automation's id (from list).","example":"7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"story":{"description":"Every story setting, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"series":{"type":"object","properties":{"enabled":{"type":"boolean"},"parts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"afterLastPart":{"type":"string","enum":["new_series","stop"]},"current":{"description":"The series being told now, and how many parts are posted.","anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partsMade":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["seriesId","title","partsMade"],"additionalProperties":false},{"type":"null"}]}},"required":["enabled","parts","afterLastPart","current"],"additionalProperties":false},"ideas":{"type":"object","properties":{"ideas":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ideas"],"additionalProperties":false},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","status","pauseReason","schedule","story","series","ideas","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"recentRuns":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"testRun":{"type":"boolean"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsUsed":{"type":"number"},"posts":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"published":{"type":"boolean"},"link":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["published","link"],"additionalProperties":false}},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","testRun","topic","projectId","videoUrl","creditsUsed","posts","error","startedAt","completedAt"],"additionalProperties":false}}},"required":["automation","recentRuns"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"automation":{"id":"7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d","name":"Fruit Drama Daily","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["18:00"],"videosPerDay":1},"story":{"species":"fruit","storyFormat":"forehead-number","formatAuto":false,"lengthSeconds":75,"language":"en","aspectRatio":"9:16","chemistry":"flirty","look":null,"scriptModel":"opus","imageModel":"nano-banana-2","videoModel":"autoclips1","captions":true,"music":"default","narrationMode":"spoken","videoSpeed":1,"partLabel":true,"characterIds":[]},"series":{"enabled":true,"parts":5,"afterLastPart":"new_series","current":null},"ideas":{"ideas":"Rich vs poor revenge stories with a twist"},"publishing":{"email":true,"library":true,"tiktok":{"enabled":true,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":5200,"approvedAt":"2026-10-27T09:00:00.000Z"},"estimatedCreditsPerRun":5200,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-10-27T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d"},"recentRuns":[{"id":"d2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f","status":"completed","testRun":false,"topic":"A cashier is mocked for her old shoes; the shop owner is her father.","projectId":"5f1e2d3c-4b5a-4968-8776-655443322110","videoUrl":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","creditsUsed":2340,"posts":{"tiktok":{"published":true,"link":"https://www.tiktok.com/@you/video/1"}},"error":null,"startedAt":"2026-10-27T09:00:00.000Z","completedAt":"2026-10-27T10:05:00.000Z"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"fruit_automations_update","summary":"Change a Fruit automation's name, schedule, story settings, series, ideas or posting.","description":"Changes the parts you send (story settings are merged into the saved ones); everything else stays. Changes apply from the next run. A change of ideas or language writes new ideas (it counts toward the free-AI daily limit). A change that raises what a day can spend above the daily limit, or any raise when it has none, is refused: set the limit first with set_spend_limit (409 spend_limit_needed). Switching posting on, adding a platform, changing the posting account or making YouTube more public needs the publish permission, and AI apps ask first.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.automations.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_automations action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The automation's name: unique on your account, at most 100 characters.","type":"string","minLength":1,"maxLength":100},"schedule":{"description":"When it runs. A new automation needs all three; an update changes only what you send.","type":"object","properties":{"timezone":{"description":"The time zone of the posting times (IANA, for example \"America/New_York\").","type":"string","minLength":1,"maxLength":64},"videosPerDay":{"description":"Videos a day, 1 to 3: one per posting time.","type":"integer","minimum":1,"maximum":3},"times":{"description":"The posting times, one per video a day (\"09:00\", 24-hour).","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}}},"additionalProperties":false},"story":{"description":"Every option of the Fruit create page, for each run's story (autoclips_options product fruit). Left out on a create: a 75-second Fruit story in the Number on Forehead format.","type":"object","properties":{"species":{"description":"Fruit or animal: Fruit AI (people with fruit heads) or Animal Stories (photoreal animal heads on people). Animal Stories come only in the story formats, take an idea (not a pasted script) and do not use the fruit character library.\nChoices:\n- fruit — Fruit AI: Fruit-headed people, every format.\n- animal — Animal Stories: Animal-headed people, story formats only.\nDefault: fruit.","type":"string","enum":["fruit","animal"]},"storyFormat":{"description":"Format: The shape of the story. Story formats (65 to 85 seconds, Pro and up) are viral micro-dramas with a world rule and a Part 2 hook; reel formats are the measured 30 to 65 second Fruit comedies; the older formats are kept for those who use them. Animal Stories take a story format only (default secret-identity). fruit_formats get shows a format's example video, beats and default look.\nChoices:\n- forehead-number — Number on Forehead: Story format: Everyone can see your number. Then it changes. (plans: pro, advanced, enterprise, ultra, legacy)\n- million-challenge — Million-Dollar Challenge: Story format: Your worst habit just became worth a million. (plans: pro, advanced, enterprise, ultra, legacy)\n- secret-identity — Secret Identity: Story format: The new kid is quiet. Nobody knows who he really is. (plans: pro, advanced, enterprise, ultra, legacy)\n- plot-twist — Emotional Plot Twist: Story format: A wrong done in plain sight. A twist nobody saw coming. (plans: pro, advanced, enterprise, ultra, legacy)\n- glow-up — Glow-Up Revenge: Story format: They called her a zero. Wait till they see her now. (plans: pro, advanced, enterprise, ultra, legacy)\n- giant-curse — Giant Curse: Story format: One spell made her enormous. Now he has to break it. (plans: pro, advanced, enterprise, ultra, legacy)\n- impossible-commission — Impossible Commission: Story format: A billionaire problem. A $5 builder. One shot. (plans: pro, advanced, enterprise, ultra, legacy)\n- countdown-trap — Countdown Trap: Story format: Ten seconds left. And someone planned this. (plans: pro, advanced, enterprise, ultra, legacy)\n- the-test — The Test: Story format: Two heirs. Three suitors. Only one passes. (plans: pro, advanced, enterprise, ultra, legacy)\n- burger-money — Rich vs Poor: Reel format: The rich one mocks the worker. Then needs them.\n- cheating — Cheating: Reel format: Caught in the act. One lie. One cold verdict.\n- cuh — Cuh: Reel format: Dad picks a favourite. Years later the other one wins.\n- correct-me — Correct Me If I'm Wrong: Reel format: He asks the wrong question. It works anyway.\n- two-paths — Two Child, Two Paths: Reel format: Two babies, two trades, one couch.\n- custom — Custom: Reel format: Your idea or your script, told your way.\n- short-film — Short Film: Classic format: Cinematic mini-movie — widescreen, real camera work. (plans: pro, advanced, enterprise, ultra, legacy)\n- reality-show — Reality Show: Classic format: Love Island style dating drama.\n- comedy — Comedy Sketch: Classic format: Short-form comedy. (plans: pro, advanced, enterprise, ultra, legacy)\n- drama — Drama Series: Classic format: Serialized dramatic storytelling. (plans: pro, advanced, enterprise, ultra, legacy)\n- educational — Educational: Classic format: Fun educational content. (plans: pro, advanced, enterprise, ultra, legacy)\n- music-video — Music Video: Classic format: Performance and dance. (plans: pro, advanced, enterprise, ultra, legacy)\n- cooking-show — Cooking Show: Classic format: Food-related scenarios. (plans: pro, advanced, enterprise, ultra, legacy)\nDefault: forehead-number.","type":"string","enum":["forehead-number","million-challenge","secret-identity","plot-twist","glow-up","giant-curse","impossible-commission","countdown-trap","the-test","burger-money","cheating","cuh","correct-me","two-paths","custom","short-film","reality-show","comedy","drama","educational","music-video","cooking-show"]},"formatAuto":{"description":"Story formats only: the director picks the story format that fits the idea best (storyFormat is the fallback). Default false.","type":"boolean"},"lengthSeconds":{"description":"How long it runs, in seconds: a story format 65, 75 or 85; any other format 30, 38, 46, 54, 60 or 65. Default: the format's own (75 or 46). Over 32 seconds needs Pro or higher.","type":"integer","minimum":20,"maximum":90},"language":{"description":"The language the characters speak (autoclips_options product fruit, option language). Default en.","type":"string","minLength":2,"maxLength":16},"aspectRatio":{"description":"Shape: The video's shape. A series keeps the shape of its Part 1.\nChoices:\n- 9:16 — 9:16: Vertical (TikTok/Reels).\n- 16:9 — 16:9: Horizontal (YouTube).\n- 1:1 — 1:1: Square.\nDefault: 9:16.","type":"string","enum":["9:16","16:9","1:1"]},"chemistry":{"description":"Chemistry: How much romance the couples show. Clothes stay on at every level.\nChoices:\n- clean — Clean: Barely touch. The story is the same.\n- flirty — Flirty: Hugs, an arm round a waist, looks that hold.\n- spicy — Spicy: Kissing and dancing too. Adds a dance track.\nDefault: flirty.","type":"string","enum":["clean","flirty","spicy"]},"look":{"description":"Look: How the cast is dressed. Left out, the format decides (Hot on glow-up, giant-curse and impossible-commission; Classic elsewhere), and an idea about a child or a teenager is always Classic by default. Hot is grown-ups (21+) only and never nudity. A series keeps its look unless a part picks one.\nChoices:\n- classic — Classic: Everyone dressed for the story.\n- hot — Hot: Glamorous grown-up leads: figure-hugging outfits, curves, cleavage. Never nudity.\nDefault: The format's own look (leave it out).","type":"string","enum":["classic","hot"]},"scriptModel":{"description":"Writer: Which AI writes the script. The writer sets the script's price.\nChoices:\n- opus — Claude Opus 5.5: Claude Opus 5.5 writes the script. (300 credits for the script)\n- gemini — Gemini 3.8 Flash: Gemini 3.8 Flash writes the script. (120 credits for the script)\n- muse — Muse Spark 1.3: Muse Spark 1.3 writes the script. (120 credits for the script)\n- kimi — Kimi K3: Kimi K3 writes the script. (200 credits for the script)\n- grok — Grok 4.6: Grok 4.6 writes the script. (110 credits for the script)\nDefault: opus.","type":"string","enum":["opus","gemini","muse","kimi","grok"]},"imageModel":{"description":"Picture model: Which model draws the character looks and the scene frames. It sets each picture's price.\nChoices:\n- nano-banana-2 — Nano Banana 2: Highest quality, best character consistency. (72 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2-high — Precision Max: Sharpest detail and the most literal prompt accuracy. (107 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2 — Precision: Same accuracy at a lower resolution — cheaper per image. (33 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-2-pro — FLUX 2 Pro: Excellent style adherence and detail. (48 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- nano-banana — Nano Banana: Good quality, faster generation. (24 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-kontext-pro — FLUX Kontext Pro: Good balance of quality and speed. (24 credits a picture)\n- flux-kontext-dev — FLUX Kontext Dev: Budget option for testing. (15 credits a picture)\n- krea-2-medium — Krea 2: Stunning aesthetics — style-reference consistency. (25 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\nDefault: nano-banana-2.","type":"string","enum":["nano-banana-2","gpt-image-2-high","gpt-image-2","flux-2-pro","nano-banana","flux-kontext-pro","flux-kontext-dev","krea-2-medium"]},"videoModel":{"description":"Video model: Which model films each scene's talking clip. The four AutoClips models and Reel are on the create page. AutoClips 1 Lite and Lite Full HD speak the lines in each character's voice (set it with the cast's voice option; voices are free). A Short Film is filmed on Cinematic Pro; the others are kept for older stories.\nChoices:\n- autoclips1 — AutoClips 1: Our main model. Strong acting, speaks every line. (12 credits a second of clip)\n- autoclips1Upscaled — AutoClips 1 1080p Upscaled: AutoClips 1, sharpened to 1080p. (16 credits a second of clip)\n- autoclips1Light — AutoClips 1 Lite: Half the price. Lines are spoken in the voices you pick. (6 credits a second of clip)\n- autoclips1LightHd — AutoClips 1 Lite Full HD: AutoClips 1 Lite drawn at full 1080p. (18 credits a second of clip)\n- autoclips — AutoClips 1 1080p Upscaled: The older name for AutoClips 1 1080p Upscaled, kept for saved stories and automations. (16 credits a second of clip)\n- minimax — Reel: Big expressive acting, one clean shot per scene, 10-second clips. (52 credits a second of clip)\n- omniMax — Pro Max: Best quality, fastest generation. (1500 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\n- veo31lite — Lite: Fast and affordable — 720p with audio. (240 credits a clip)\n- klingStd — Cinematic: Multi-shot — several camera angles cut together in one take. (600 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\n- klingPro — Cinematic Pro: Multi-shot at the highest quality tier. (810 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\nDefault: autoclips1.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd","autoclips","minimax","omniMax","veo31lite","klingStd","klingPro"]},"captions":{"description":"Burned-in word-by-word captions. Default true (a silent Short Film has none).","type":"boolean"},"music":{"title":"Background music (Fruit AI Stories and Animal Stories option music)","description":"Background music: The music bed, as \"<shelf>:<track id>\" (fai, popular or v3) or \"none\". Left out: story formats start on a copyright-free sad bed; other formats start with no music.\nOne of 333 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=fruit&option=music) to see them all.\nChoices:\n- none — No music: The story plays with its voices and sound only.\n- fai:fai-batida-funk — Batida Funk: Fruit picks shelf.\n- fai:fai-popular — Popular: Fruit picks shelf.\n- fai:fai-slowed — Slowed: Fruit picks shelf.\n- fai:fai-normal — Normal: Fruit picks shelf.\n- popular:hide-and-sneak — Hide and Sneak: Popular shelf.\n- popular:old-time-circus — Old Time Circus: Popular shelf.\n- popular:lurking-behind — Lurking Behind: Popular shelf.\n- popular:ce-burning-memory — It's Just a Burning Memory: Popular shelf.\n- popular:ce-f-down — F.Down: Popular shelf.\n- popular:ce-school-rooftop — School Rooftop (Bird Sounds): Popular shelf.\n- popular:ce-promise-reprise — Promise (Reprise): Popular shelf.\n- popular:ce-everything-in-its-right-place — Everything In Its Right Place (Instrumental): Popular shelf.\n- popular:ce-six-forty-seven — Six Forty Seven: Popular shelf.\n- popular:ce-numbers — Numbers (Instrumental): Popular shelf.\n- popular:ce-fallen-down — Fallen Down (Panic Room): Popular shelf.\n- popular:ce-char-remix — Char (Remix) Slowed: Popular shelf.\n- popular:ce-empathy — Empathy (Slowed + Reverb): Popular shelf.\n- popular:ce-aleph — ALEPH (Slowed + Reverb): Popular shelf.\n- popular:ce-solitude — Solitude (Slowed): Popular shelf.\n- popular:ce-closed-slowed — Closed (Slowed + Reverb): Popular shelf.\n- popular:ce-silhouette — Silhouette (Slowed Best Part): Popular shelf.\n- popular:ce-country-roads — Take Me Home, Country Roads (Karaoke): Popular shelf.\n- popular:ce-house-rising-sun — The House Of The Rising Sun (Instrumental): Popular shelf.\n- popular:ce-feeling-blue — Feeling Blue: Popular shelf.\n- popular:ce-stargazing — Stargazing (Sped Up): Popular shelf.\n- v3:animals-wildlife-01-wild-kingdom-v1 — Wild Kingdom: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-01-wild-kingdom-v2 — Wild Kingdom: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-02-migration-path-v1 — Migration Path: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-02-migration-path-v2 — Migration Path: Copyright-free shelf, copyright-free.\n…and 303 more.\nDefault: The format's default bed (leave it out).","type":"string"},"narrationMode":{"description":"Spoken or silent (Short Film): Short Film only: spoken (dense dialogue) or silent (no dialogue at all, the story told in pictures). Every other format is spoken. A series keeps it.\nChoices:\n- spoken — Spoken: The characters talk.\n- silent — Silent: Nobody speaks; no captions.\nDefault: spoken.","type":"string","enum":["spoken","silent"]},"videoSpeed":{"description":"Speed: How fast the finished video plays, 1x to 2x in steps of 0.1. Changing it on a finished video needs a new render. Series parts keep the speed of the series unless a part picks one. From 1 to 2 x, in steps of 0.1. Default: 1.","type":"number","minimum":1,"maximum":2,"multipleOf":0.1},"partLabel":{"description":"Story formats: show the \"PART N\" label. Default true.","type":"boolean"},"characterIds":{"description":"Fruit AI only: up to 8 characters from your library (yours, a preset or a public one) to cast. Left out: the writer invents the whole cast.","maxItems":8,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$"}}},"additionalProperties":false},"series":{"type":"object","properties":{"enabled":{"description":"true: Part 1, then each run makes the next part from the last part's cliffhanger with the same characters. false: a new story every run.","type":"boolean"},"parts":{"description":"Parts in a series, 2 to 10; the last one closes the story.","type":"integer","minimum":2,"maximum":10},"afterLastPart":{"description":"After the last part: new_series (the next run starts a new series) or stop (the automation pauses).","type":"string","enum":["new_series","stop"]}},"additionalProperties":false},"ideas":{"type":"object","properties":{"ideas":{"description":"What the stories are about, in your words (\"rich vs poor revenge stories\", \"office romance with a twist\"). Every run gets a new idea written from it.","type":"string","minLength":1,"maxLength":2000}},"required":["ideas"],"additionalProperties":false},"publishing":{"description":"Where each video goes. Switching posting on, changing the posting account or making YouTube videos more public needs the publish permission; only the platforms you send change.","type":"object","properties":{"email":{"description":"Email you when each video is ready.","type":"boolean"},"library":{"description":"Keep each video in My Videos.","type":"boolean"},"tiktok":{"description":"Posting to TikTok.","type":"object","properties":{"enabled":{"description":"Post every video to TikTok.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"youtube":{"description":"Posting to YouTube.","type":"object","properties":{"enabled":{"description":"Post every video to YouTube.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"},"privacy":{"description":"public, unlisted or private (default private; private videos get no comments, so no votes).","type":"string","enum":["public","unlisted","private"]},"categoryId":{"description":"The YouTube category id (2 Autos & Vehicles, 23 Comedy, 27 Education, 24 Entertainment, 1 Film & Animation, 20 Gaming, 26 Howto & Style, 10 Music, 25 News & Politics, 29 Nonprofits & Activism, 22 People & Blogs, 15 Pets & Animals, 28 Science & Technology, 17 Sports, 19 Travel & Events).","type":"string","enum":["1","2","10","15","17","19","20","22","23","24","25","26","27","28","29"]},"useAIMetadata":{"description":"Write the title and description from the video (default true).","type":"boolean"}},"required":["enabled"],"additionalProperties":false},"instagram":{"description":"Posting to Instagram.","type":"object","properties":{"enabled":{"description":"Post every video to Instagram.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"facebook":{"description":"Posting to Facebook.","type":"object","properties":{"enabled":{"description":"Post every video to Facebook.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"twitter":{"description":"Posting to X.","type":"object","properties":{"enabled":{"description":"Post every video to X.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"snapchat":{"description":"Posting to Snapchat.","type":"object","properties":{"enabled":{"description":"Post every video to Snapchat.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"example":{"story":{"species":"animal","look":"hot"}}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120},"description":"The automation's id (from list).","example":"7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"story":{"description":"Every story setting, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"series":{"type":"object","properties":{"enabled":{"type":"boolean"},"parts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"afterLastPart":{"type":"string","enum":["new_series","stop"]},"current":{"description":"The series being told now, and how many parts are posted.","anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partsMade":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["seriesId","title","partsMade"],"additionalProperties":false},{"type":"null"}]}},"required":["enabled","parts","afterLastPart","current"],"additionalProperties":false},"ideas":{"type":"object","properties":{"ideas":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ideas"],"additionalProperties":false},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","status","pauseReason","schedule","story","series","ideas","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"ideasRewritten":{"type":"boolean"}},"required":["automation","ideasRewritten"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d","name":"Fruit Drama Daily","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["18:00"],"videosPerDay":1},"story":{"species":"fruit","storyFormat":"forehead-number","formatAuto":false,"lengthSeconds":75,"language":"en","aspectRatio":"9:16","chemistry":"flirty","look":null,"scriptModel":"opus","imageModel":"nano-banana-2","videoModel":"autoclips1","captions":true,"music":"default","narrationMode":"spoken","videoSpeed":1,"partLabel":true,"characterIds":[]},"series":{"enabled":true,"parts":5,"afterLastPart":"new_series","current":null},"ideas":{"ideas":"Rich vs poor revenge stories with a twist"},"publishing":{"email":true,"library":true,"tiktok":{"enabled":true,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":5200,"approvedAt":"2026-10-27T09:00:00.000Z"},"estimatedCreditsPerRun":5200,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-10-27T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d"},"ideasRewritten":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"fruit_automations_delete","summary":"Delete a Fruit automation and its run history. Its stories stay in My Videos.","description":"Deletes the automation and its run history. Refused while a story is being made (409 run_active: wait, or cancel_run).\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"fruit.automations.delete","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_automations action=delete","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120},"description":"The automation's id (from list).","example":"7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"deleted":true,"id":"7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/automations/{automationId}/pause":{"post":{"operationId":"fruit_automations_pause","summary":"Pause a Fruit automation; it makes nothing until it is resumed.","description":"Pause a Fruit automation; it makes nothing until it is resumed.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.automations.pause","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_automations action=pause","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120},"description":"The automation's id (from list).","example":"7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"story":{"description":"Every story setting, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"series":{"type":"object","properties":{"enabled":{"type":"boolean"},"parts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"afterLastPart":{"type":"string","enum":["new_series","stop"]},"current":{"description":"The series being told now, and how many parts are posted.","anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partsMade":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["seriesId","title","partsMade"],"additionalProperties":false},{"type":"null"}]}},"required":["enabled","parts","afterLastPart","current"],"additionalProperties":false},"ideas":{"type":"object","properties":{"ideas":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ideas"],"additionalProperties":false},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","status","pauseReason","schedule","story","series","ideas","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"changed":{"type":"boolean"}},"required":["automation","changed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d","name":"Fruit Drama Daily","status":"paused","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["18:00"],"videosPerDay":1},"story":{"species":"fruit","storyFormat":"forehead-number","formatAuto":false,"lengthSeconds":75,"language":"en","aspectRatio":"9:16","chemistry":"flirty","look":null,"scriptModel":"opus","imageModel":"nano-banana-2","videoModel":"autoclips1","captions":true,"music":"default","narrationMode":"spoken","videoSpeed":1,"partLabel":true,"characterIds":[]},"series":{"enabled":true,"parts":5,"afterLastPart":"new_series","current":null},"ideas":{"ideas":"Rich vs poor revenge stories with a twist"},"publishing":{"email":true,"library":true,"tiktok":{"enabled":true,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":5200,"approvedAt":"2026-10-27T09:00:00.000Z"},"estimatedCreditsPerRun":5200,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-10-27T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d"},"changed":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/automations/{automationId}/resume":{"post":{"operationId":"fruit_automations_resume","summary":"Resume a paused Fruit automation at its next posting time.","description":"Resumes a paused automation from its next posting time. It needs a daily spending limit (409 spend_limit_needed). Resuming an automation that posts needs the publish permission, and AI apps ask first.\n\n**Permissions:** edit, spend.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"fruit.automations.resume","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_automations action=resume","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120},"description":"The automation's id (from list).","example":"7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"story":{"description":"Every story setting, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"series":{"type":"object","properties":{"enabled":{"type":"boolean"},"parts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"afterLastPart":{"type":"string","enum":["new_series","stop"]},"current":{"description":"The series being told now, and how many parts are posted.","anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partsMade":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["seriesId","title","partsMade"],"additionalProperties":false},{"type":"null"}]}},"required":["enabled","parts","afterLastPart","current"],"additionalProperties":false},"ideas":{"type":"object","properties":{"ideas":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ideas"],"additionalProperties":false},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","status","pauseReason","schedule","story","series","ideas","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"changed":{"type":"boolean"}},"required":["automation","changed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d","name":"Fruit Drama Daily","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["18:00"],"videosPerDay":1},"story":{"species":"fruit","storyFormat":"forehead-number","formatAuto":false,"lengthSeconds":75,"language":"en","aspectRatio":"9:16","chemistry":"flirty","look":null,"scriptModel":"opus","imageModel":"nano-banana-2","videoModel":"autoclips1","captions":true,"music":"default","narrationMode":"spoken","videoSpeed":1,"partLabel":true,"characterIds":[]},"series":{"enabled":true,"parts":5,"afterLastPart":"new_series","current":null},"ideas":{"ideas":"Rich vs poor revenge stories with a twist"},"publishing":{"email":true,"library":true,"tiktok":{"enabled":true,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":5200,"approvedAt":"2026-10-27T09:00:00.000Z"},"estimatedCreditsPerRun":5200,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-10-27T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d"},"changed":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/automations/{automationId}/runs":{"post":{"operationId":"fruit_automations_run_now","summary":"Make the next story of a Fruit automation now, and post it as the schedule would. Answers with a job.","description":"Makes the automation's next story right now (the app's Test button: the next part of its series, or a new story) and posts it where the automation posts. The price is one story at its most; each step is charged as it is made and what does not come out is refunded. One run at a time (409 run_in_progress), at most one every 5 minutes (429). It answers with a job: follow it with autoclips_jobs get (about 20 to 70 minutes).\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.automations.run_now","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_automations action=run_now","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120},"description":"The automation's id (from list).","example":"7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"run":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}},"required":["id","status"],"additionalProperties":false},"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false}},"required":["run","job"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"run":{"id":"d2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f","status":"generating"},"job":{"id":"job_019a1b2c3d4e5f60718293d1","product":"fruit","kind":"fruit.automation_run","resource":{"type":"automation_run","id":"d2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f"},"status":"queued","step":"Starting the run","progress":null,"result":null,"error":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T09:00:00.000Z","finishedAt":null,"poll_after_seconds":30}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"fruit_automations_runs","summary":"List a Fruit automation's recent runs: the idea, the story, where it posted and what it used.","description":"List a Fruit automation's recent runs: the idea, the story, where it posted and what it used.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"fruit.automations.runs","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_automations action=runs","parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120},"description":"The automation's id (from list).","example":"7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50},"example":5},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","generating","completed","failed","cancelled"]}}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runs":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"testRun":{"type":"boolean"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsUsed":{"type":"number"},"posts":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"published":{"type":"boolean"},"link":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["published","link"],"additionalProperties":false}},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","testRun","topic","projectId","videoUrl","creditsUsed","posts","error","startedAt","completedAt"],"additionalProperties":false}}},"required":["runs"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"runs":[{"id":"d2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f","status":"completed","testRun":false,"topic":"A cashier is mocked for her old shoes; the shop owner is her father.","projectId":"5f1e2d3c-4b5a-4968-8776-655443322110","videoUrl":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","creditsUsed":2340,"posts":{"tiktok":{"published":true,"link":"https://www.tiktok.com/@you/video/1"}},"error":null,"startedAt":"2026-10-27T09:00:00.000Z","completedAt":"2026-10-27T10:05:00.000Z"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/automations/{automationId}/runs/cancel":{"post":{"operationId":"fruit_automations_cancel_run","summary":"Stop the story a Fruit automation is making now. Nothing is posted.","description":"Stops the live run (or the one runId names): its story's autopilot is switched off, so no later step is started or charged; a step already running finishes and what does not come out is refunded. The story stays in My Videos as far as it got. 404 when no run is live.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.automations.cancel_run","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_automations action=cancel_run","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string","minLength":1,"maxLength":120}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120},"description":"The automation's id (from list).","example":"7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runId":{"anyOf":[{"type":"string"},{"type":"null"}]},"cancelled":{"type":"boolean"},"creditsRefunded":{"type":"number"}},"required":["runId","cancelled","creditsRefunded"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"runId":"d2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f","cancelled":true,"creditsRefunded":0}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/automations/{automationId}/spend-limit":{"put":{"operationId":"fruit_automations_set_spend_limit","summary":"Set how much a Fruit automation may spend a day.","description":"Sets the daily spending limit: a run that would pass it is skipped until the next day (a run is settled after it is made, so one step's final cost can run a little over). It must allow at least one story at its most (400 spend_limit_too_low). It resumes nothing.\n\n**Permissions:** spend.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. Fruit automation day stops before a step that would go past the limit, but one step's final cost can run a little over, so the limit is not the most it can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend"]}],"x-autoclips-operation":"fruit.automations.set_spend_limit","x-autoclips-scopes":["spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_automations action=set_spend_limit","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"spendLimitPerDay":{"description":"The most it may spend a day, in credits (1 to 100,000). Left out: one day of runs at their most.","type":"integer","minimum":1,"maximum":100000},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["spendLimitPerDay"],"additionalProperties":false},"example":{"spendLimitPerDay":10400}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120},"description":"The automation's id (from list).","example":"7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"story":{"description":"Every story setting, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"series":{"type":"object","properties":{"enabled":{"type":"boolean"},"parts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"afterLastPart":{"type":"string","enum":["new_series","stop"]},"current":{"description":"The series being told now, and how many parts are posted.","anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partsMade":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["seriesId","title","partsMade"],"additionalProperties":false},{"type":"null"}]}},"required":["enabled","parts","afterLastPart","current"],"additionalProperties":false},"ideas":{"type":"object","properties":{"ideas":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ideas"],"additionalProperties":false},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","status","pauseReason","schedule","story","series","ideas","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false}},"required":["automation"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d","name":"Fruit Drama Daily","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["18:00"],"videosPerDay":1},"story":{"species":"fruit","storyFormat":"forehead-number","formatAuto":false,"lengthSeconds":75,"language":"en","aspectRatio":"9:16","chemistry":"flirty","look":null,"scriptModel":"opus","imageModel":"nano-banana-2","videoModel":"autoclips1","captions":true,"music":"default","narrationMode":"spoken","videoSpeed":1,"partLabel":true,"characterIds":[]},"series":{"enabled":true,"parts":5,"afterLastPart":"new_series","current":null},"ideas":{"ideas":"Rich vs poor revenge stories with a twist"},"publishing":{"email":true,"library":true,"tiktok":{"enabled":true,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":10400,"approvedAt":"2026-10-27T09:00:00.000Z"},"estimatedCreditsPerRun":5200,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-10-27T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/7c2e7c1d-9a3f-4e8b-b6c2-1d0e9f8a7b6d"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/cast/suggest":{"post":{"operationId":"fruit_cast_suggest","summary":"Library characters that fit a story idea, with why (free; counts toward the free-AI daily limit).","description":"Reads your idea and picks characters from your library, the presets and public characters that fit it, with a reason each and the roles still missing. Send the picks as characterIds to fruit_story create. Fruit AI only.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"fruit.cast.suggest","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_cast action=suggest","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idea":{"type":"string","minLength":10,"maxLength":2000},"maxCount":{"description":"At most this many (1-8, default 6).","type":"integer","minimum":1,"maximum":8}},"required":["idea"],"additionalProperties":false},"example":{"idea":"Three fruit thieves try to rob a casino run by a pineapple boss."}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"characters":{"type":"array","items":{"type":"object","properties":{"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["characterId","name","kind","role","reason","thumbnailUrl"],"additionalProperties":false}},"gaps":{"type":"array","items":{"type":"string"}}},"required":["characters","gaps"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"characters":[{"characterId":"66f0a1b2c3d4e5f601234567","name":"Don Pineapple","kind":"pineapple","role":"lead","reason":"He runs the casino.","thumbnailUrl":null}],"gaps":["a getaway driver"]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/characters":{"get":{"operationId":"fruit_characters_list","summary":"Your Fruit characters, the presets and public characters.","description":"Your Fruit characters, the presets and public characters.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"fruit.characters.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_characters action=list","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"characters":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"personality":{"anyOf":[{"type":"string"},{"type":"null"}]},"backstory":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"referenceSheet":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"preset":{"type":"boolean"},"public":{"type":"boolean"},"faceMode":{"description":"Made from a real face photo.","type":"boolean"},"tags":{"type":"array","items":{"type":"string"}}},"required":["id","name","kind","gender","age","personality","backstory","imageUrl","referenceSheet","preset","public","faceMode","tags"],"additionalProperties":false}},"presets":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"personality":{"anyOf":[{"type":"string"},{"type":"null"}]},"backstory":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"referenceSheet":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"preset":{"type":"boolean"},"public":{"type":"boolean"},"faceMode":{"description":"Made from a real face photo.","type":"boolean"},"tags":{"type":"array","items":{"type":"string"}}},"required":["id","name","kind","gender","age","personality","backstory","imageUrl","referenceSheet","preset","public","faceMode","tags"],"additionalProperties":false}},"publicCharacters":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"personality":{"anyOf":[{"type":"string"},{"type":"null"}]},"backstory":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"referenceSheet":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"preset":{"type":"boolean"},"public":{"type":"boolean"},"faceMode":{"description":"Made from a real face photo.","type":"boolean"},"tags":{"type":"array","items":{"type":"string"}}},"required":["id","name","kind","gender","age","personality","backstory","imageUrl","referenceSheet","preset","public","faceMode","tags"],"additionalProperties":false}},"limit":{"anyOf":[{"type":"number"},{"type":"null"}]},"canCreate":{"type":"boolean"},"autoPublish":{"type":"boolean"}},"required":["characters","presets","publicCharacters","limit","canCreate","autoPublish"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"characters":[{"id":"66f0a1b2c3d4e5f601234567","name":"Mango Mia","kind":"mango","gender":"female","age":24,"personality":"Bold and funny.","backstory":null,"imageUrl":"https://media.autoclips.app/fruit-characters/u/mango.png","referenceSheet":{},"preset":false,"public":false,"faceMode":false,"tags":[]}],"presets":[],"publicCharacters":[],"limit":20,"canCreate":true,"autoPublish":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"fruit_characters_create","summary":"Save a character to your library (free; your plan's character limit applies).","description":"Saves a Fruit character with its picture (imageUrl from generate_images today, or mediaId from autoclips_media) and, optionally, its reference angles (from generate_sheet). It is shared with everyone only when auto_publish is on.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.characters.create","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_characters action=create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":60},"kind":{"description":"The fruit of their head (\"mango\").","type":"string","minLength":1,"maxLength":40},"gender":{"type":"string","enum":["female","male","non-binary"]},"age":{"type":"integer","minimum":1,"maximum":99},"personality":{"type":"string","maxLength":500},"backstory":{"type":"string","maxLength":1000},"appearance":{"type":"string","maxLength":500},"tags":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":40}},"imageUrl":{"type":"string","maxLength":2048,"format":"uri"},"mediaId":{"type":"string","minLength":1,"maxLength":64},"referenceSheet":{"description":"Angles from generate_sheet.","type":"object","propertyNames":{"type":"string","pattern":"^[a-zA-Z]{2,30}$"},"additionalProperties":{"type":"string","maxLength":2048,"format":"uri"}},"imageModel":{"description":"Picture model: Which model draws the character looks and the scene frames. It sets each picture's price.\nChoices:\n- nano-banana-2 — Nano Banana 2: Highest quality, best character consistency. (72 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2-high — Precision Max: Sharpest detail and the most literal prompt accuracy. (107 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2 — Precision: Same accuracy at a lower resolution — cheaper per image. (33 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-2-pro — FLUX 2 Pro: Excellent style adherence and detail. (48 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- nano-banana — Nano Banana: Good quality, faster generation. (24 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-kontext-pro — FLUX Kontext Pro: Good balance of quality and speed. (24 credits a picture)\n- flux-kontext-dev — FLUX Kontext Dev: Budget option for testing. (15 credits a picture)\n- krea-2-medium — Krea 2: Stunning aesthetics — style-reference consistency. (25 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\nDefault: nano-banana-2.","type":"string","enum":["nano-banana-2","gpt-image-2-high","gpt-image-2","flux-2-pro","nano-banana","flux-kontext-pro","flux-kontext-dev","krea-2-medium"]}},"required":["name","kind"],"additionalProperties":false},"example":{"name":"Mango Mia","kind":"mango","gender":"female","age":24,"imageUrl":"https://replicate.delivery/example/0.png"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"character":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"personality":{"anyOf":[{"type":"string"},{"type":"null"}]},"backstory":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"referenceSheet":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"preset":{"type":"boolean"},"public":{"type":"boolean"},"faceMode":{"description":"Made from a real face photo.","type":"boolean"},"tags":{"type":"array","items":{"type":"string"}}},"required":["id","name","kind","gender","age","personality","backstory","imageUrl","referenceSheet","preset","public","faceMode","tags"],"additionalProperties":false}},"required":["character"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"character":{"id":"66f0a1b2c3d4e5f601234567","name":"Mango Mia","kind":"mango","gender":"female","age":24,"personality":"Bold and funny.","backstory":null,"imageUrl":"https://media.autoclips.app/fruit-characters/u/mango.png","referenceSheet":{},"preset":false,"public":false,"faceMode":false,"tags":[]}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/characters/analyze-face":{"post":{"operationId":"fruit_characters_analyze_face","summary":"Suggest a character's details from a face photo (free; counts toward the free-AI daily limit).","description":"Suggest a character's details from a face photo (free; counts toward the free-AI daily limit).\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"fruit.characters.analyze_face","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_characters action=analyze_face","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"facePhotoMediaId":{"description":"A face photo of yours (autoclips_media).","type":"string","minLength":1,"maxLength":64},"name":{"type":"string","maxLength":60},"kind":{"type":"string","maxLength":40}},"required":["facePhotoMediaId"],"additionalProperties":false},"example":{"facePhotoMediaId":"6710aa11bb22cc33dd44ee55"}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"suggestions":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["suggestions"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"suggestions":{"gender":"female","age":28}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/characters/auto-publish":{"put":{"operationId":"fruit_characters_auto_publish","summary":"Share the characters you make with everyone, or keep them to yourself (free).","description":"Share the characters you make with everyone, or keep them to yourself (free).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.characters.auto_publish","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_characters action=auto_publish","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"example":{"enabled":false}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"enabled":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/characters/images":{"post":{"operationId":"fruit_characters_generate_images","summary":"Draw 4 options of a new character, optionally from a face photo. Charges 4 pictures.","description":"Draws four options of a new Fruit character from its details; with facePhotoMediaId (a picture in autoclips_media) the character gets that person's face (face mode, always on Nano Banana 2). 4 pictures at the model's price; refunded only if none comes out. Save the one you like with create (imageUrl).\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.characters.generate_images","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_characters action=generate_images","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"description":"The fruit of their head (\"mango\").","type":"string","minLength":1,"maxLength":40},"name":{"type":"string","minLength":2,"maxLength":60},"gender":{"type":"string","enum":["female","male","non-binary"]},"age":{"type":"integer","minimum":1,"maximum":99},"personality":{"type":"string","maxLength":500},"visualStyle":{"type":"string","enum":["3d-stylized","realistic","cartoon"]},"outfit":{"type":"string","maxLength":300},"height":{"type":"string","enum":["short","average","tall"]},"bodyType":{"type":"string","enum":["slim","fit","curvy","thick","shredded","chubby","plus-size"]},"appearance":{"type":"string","maxLength":500},"imageModel":{"description":"Picture model: Which model draws the character looks and the scene frames. It sets each picture's price.\nChoices:\n- nano-banana-2 — Nano Banana 2: Highest quality, best character consistency. (72 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2-high — Precision Max: Sharpest detail and the most literal prompt accuracy. (107 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2 — Precision: Same accuracy at a lower resolution — cheaper per image. (33 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-2-pro — FLUX 2 Pro: Excellent style adherence and detail. (48 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- nano-banana — Nano Banana: Good quality, faster generation. (24 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-kontext-pro — FLUX Kontext Pro: Good balance of quality and speed. (24 credits a picture)\n- flux-kontext-dev — FLUX Kontext Dev: Budget option for testing. (15 credits a picture)\n- krea-2-medium — Krea 2: Stunning aesthetics — style-reference consistency. (25 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\nDefault: nano-banana-2.","type":"string","enum":["nano-banana-2","gpt-image-2-high","gpt-image-2","flux-2-pro","nano-banana","flux-kontext-pro","flux-kontext-dev","krea-2-medium"]},"facePhotoMediaId":{"description":"A face photo of yours (autoclips_media).","type":"string","minLength":1,"maxLength":64},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"required":["kind","name"],"additionalProperties":false},"example":{"kind":"mango","name":"Mango Mia","gender":"female","age":24}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"images":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"url":{"type":"string"}},"required":["index","url"],"additionalProperties":false}},"creditsCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["images","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"images":[{"index":0,"url":"https://replicate.delivery/example/0.png"}],"creditsCharged":288}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/characters/sheet":{"post":{"operationId":"fruit_characters_generate_sheet","summary":"Draw a character's reference angles from one of its pictures. Charges one picture an angle.","description":"Draw a character's reference angles from one of its pictures. Charges one picture an angle.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.characters.generate_sheet","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_characters action=generate_sheet","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"description":"The fruit of their head (\"mango\").","type":"string","minLength":1,"maxLength":40},"name":{"type":"string","minLength":2,"maxLength":60},"visualStyle":{"type":"string","enum":["3d-stylized","realistic","cartoon"]},"imageModel":{"description":"Picture model: Which model draws the character looks and the scene frames. It sets each picture's price.\nChoices:\n- nano-banana-2 — Nano Banana 2: Highest quality, best character consistency. (72 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2-high — Precision Max: Sharpest detail and the most literal prompt accuracy. (107 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2 — Precision: Same accuracy at a lower resolution — cheaper per image. (33 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-2-pro — FLUX 2 Pro: Excellent style adherence and detail. (48 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- nano-banana — Nano Banana: Good quality, faster generation. (24 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-kontext-pro — FLUX Kontext Pro: Good balance of quality and speed. (24 credits a picture)\n- flux-kontext-dev — FLUX Kontext Dev: Budget option for testing. (15 credits a picture)\n- krea-2-medium — Krea 2: Stunning aesthetics — style-reference consistency. (25 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\nDefault: nano-banana-2.","type":"string","enum":["nano-banana-2","gpt-image-2-high","gpt-image-2","flux-2-pro","nano-banana","flux-kontext-pro","flux-kontext-dev","krea-2-medium"]},"imageUrl":{"description":"A picture generate_images drew for you today.","type":"string","maxLength":2048,"format":"uri"},"mediaId":{"description":"Or a picture of yours (autoclips_media).","type":"string","minLength":1,"maxLength":64},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"required":["kind","name"],"additionalProperties":false},"example":{"kind":"mango","name":"Mango Mia","imageUrl":"https://replicate.delivery/example/0.png"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"referenceSheet":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"generated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"creditsCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["referenceSheet","generated","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"referenceSheet":{"front":"https://media.autoclips.app/fruit-characters/u/front.png"},"generated":1,"creditsCharged":72}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/characters/{characterId}":{"get":{"operationId":"fruit_characters_get","summary":"One character (yours, a preset or a public one).","description":"One character (yours, a preset or a public one).\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"fruit.characters.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_characters action=get","parameters":[{"name":"characterId","in":"path","required":true,"schema":{"description":"The character (fruit_characters list).","type":"string","pattern":"^[a-f0-9]{24}$"},"description":"The character (fruit_characters list).","example":"66f0a1b2c3d4e5f601234567"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"character":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"personality":{"anyOf":[{"type":"string"},{"type":"null"}]},"backstory":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"referenceSheet":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"preset":{"type":"boolean"},"public":{"type":"boolean"},"faceMode":{"description":"Made from a real face photo.","type":"boolean"},"tags":{"type":"array","items":{"type":"string"}}},"required":["id","name","kind","gender","age","personality","backstory","imageUrl","referenceSheet","preset","public","faceMode","tags"],"additionalProperties":false}},"required":["character"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"character":{"id":"66f0a1b2c3d4e5f601234567","name":"Mango Mia","kind":"mango","gender":"female","age":24,"personality":"Bold and funny.","backstory":null,"imageUrl":"https://media.autoclips.app/fruit-characters/u/mango.png","referenceSheet":{},"preset":false,"public":false,"faceMode":false,"tags":[]}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"fruit_characters_update","summary":"Change one of your characters (free).","description":"Change one of your characters (free).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.characters.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_characters action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":60},"personality":{"type":"string","maxLength":500},"backstory":{"type":"string","maxLength":1000},"appearance":{"type":"string","maxLength":500},"tags":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":40}},"imageUrl":{"type":"string","maxLength":2048,"format":"uri"},"mediaId":{"type":"string","minLength":1,"maxLength":64},"referenceSheet":{"type":"object","propertyNames":{"type":"string","pattern":"^[a-zA-Z]{2,30}$"},"additionalProperties":{"type":"string","maxLength":2048,"format":"uri"}}},"additionalProperties":false},"example":{"backstory":"Grew up above a market stall."}}}},"parameters":[{"name":"characterId","in":"path","required":true,"schema":{"description":"The character (fruit_characters list).","type":"string","pattern":"^[a-f0-9]{24}$"},"description":"The character (fruit_characters list).","example":"66f0a1b2c3d4e5f601234567"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"character":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"personality":{"anyOf":[{"type":"string"},{"type":"null"}]},"backstory":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"referenceSheet":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"preset":{"type":"boolean"},"public":{"type":"boolean"},"faceMode":{"description":"Made from a real face photo.","type":"boolean"},"tags":{"type":"array","items":{"type":"string"}}},"required":["id","name","kind","gender","age","personality","backstory","imageUrl","referenceSheet","preset","public","faceMode","tags"],"additionalProperties":false}},"required":["character"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"character":{"id":"66f0a1b2c3d4e5f601234567","name":"Mango Mia","kind":"mango","gender":"female","age":24,"personality":"Bold and funny.","backstory":null,"imageUrl":"https://media.autoclips.app/fruit-characters/u/mango.png","referenceSheet":{},"preset":false,"public":false,"faceMode":false,"tags":[]}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"fruit_characters_delete","summary":"Delete one of your characters. Stories already made keep them.","description":"Delete one of your characters. Stories already made keep them.\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"fruit.characters.delete","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_characters action=delete","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"characterId","in":"path","required":true,"schema":{"description":"The character (fruit_characters list).","type":"string","pattern":"^[a-f0-9]{24}$"},"description":"The character (fruit_characters list).","example":"66f0a1b2c3d4e5f601234567"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"deleted":true,"id":"66f0a1b2c3d4e5f601234567"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/formats":{"get":{"operationId":"fruit_formats_list","summary":"Every Fruit AI and Animal Stories format, with its example video, beats, default look, lengths and plan.","description":"Every format a Fruit or Animal story can be made in, in the create page's order: the story formats (viral micro-dramas, 65 to 85 seconds, Pro and up) with their example video and poster per species, their beats, starter ideas and default look; the reel formats (30 to 65 second comedies); and the classic formats. Filter by species to see what Animal Stories can make.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"fruit.formats.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_formats action=list","parameters":[{"name":"species","in":"query","required":false,"schema":{"description":"Only the formats this species can act.","type":"string","enum":["fruit","animal"]},"description":"Only the formats this species can act.","example":"animal"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"formats":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"tagline":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"story: the 65-85 s viral micro-dramas (Pro and up); reel: the 30-65 s Fruit comedies; classic: the older formats.","type":"string","enum":["story","reel","classic"]},"species":{"description":"Who can act it: fruit (Fruit AI), animal (Animal Stories).","type":"array","items":{"type":"string","enum":["fruit","animal"]}},"plans":{"description":"null: every plan; otherwise Pro and up (and legacy plans).","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"lengths":{"description":"The lengths it is made at, in seconds (lengthSeconds).","type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"defaultLength":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"look":{"description":"Its default look (look).","type":"string","enum":["classic","hot"]},"samples":{"description":"An example video with sound and its poster, per species (null where none is made yet).","anyOf":[{"type":"object","properties":{"fruit":{"anyOf":[{"type":"object","properties":{"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["videoUrl","posterUrl"],"additionalProperties":false},{"type":"null"}]},"animal":{"anyOf":[{"type":"object","properties":{"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["videoUrl","posterUrl"],"additionalProperties":false},{"type":"null"}]}},"required":["fruit","animal"],"additionalProperties":false},{"type":"null"}]},"preview":{"anyOf":[{"type":"object","properties":{"soundOff":{"anyOf":[{"type":"string"},{"type":"null"}]},"steps":{"type":"array","items":{"type":"object","properties":{"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["label","text"],"additionalProperties":false}},"ideas":{"description":"Starter ideas per species.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["soundOff","steps","ideas"],"additionalProperties":false},{"type":"null"}]},"ending":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","label","tagline","kind","species","plans","lengths","defaultLength","look","samples","preview","ending"],"additionalProperties":false}}},"required":["formats"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"formats":[{"id":"forehead-number","label":"Number on Forehead","tagline":"Everyone can see your number. Then it changes.","kind":"story","species":["fruit","animal"],"plans":["pro","advanced","enterprise","ultra","legacy"],"lengths":[65,75,85],"defaultLength":75,"look":"classic","samples":{"fruit":{"videoUrl":"https://media.autoclips.app/clips/fruit-formats/forehead-number/sample-fruit.mp4","posterUrl":"https://media.autoclips.app/clips/fruit-formats/forehead-number/poster-fruit.jpg"},"animal":null},"preview":{"soundOff":"Every forehead shows a number everyone believes.","steps":[{"label":"Hook","text":"Two numbers are compared in the first second."}],"ideas":{"fruit":["A poor boy with $5 on his forehead starts at a school where everyone has millions."]}},"ending":null}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/formats/{formatId}":{"get":{"operationId":"fruit_formats_get","summary":"One Fruit or Animal story format in full.","description":"One Fruit or Animal story format in full.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"fruit.formats.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_formats action=get","parameters":[{"name":"formatId","in":"path","required":true,"schema":{"description":"The format id (fruit_formats list).","type":"string","minLength":1,"maxLength":60},"description":"The format id (fruit_formats list).","example":"forehead-number"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"format":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"tagline":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"story: the 65-85 s viral micro-dramas (Pro and up); reel: the 30-65 s Fruit comedies; classic: the older formats.","type":"string","enum":["story","reel","classic"]},"species":{"description":"Who can act it: fruit (Fruit AI), animal (Animal Stories).","type":"array","items":{"type":"string","enum":["fruit","animal"]}},"plans":{"description":"null: every plan; otherwise Pro and up (and legacy plans).","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"lengths":{"description":"The lengths it is made at, in seconds (lengthSeconds).","type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"defaultLength":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"look":{"description":"Its default look (look).","type":"string","enum":["classic","hot"]},"samples":{"description":"An example video with sound and its poster, per species (null where none is made yet).","anyOf":[{"type":"object","properties":{"fruit":{"anyOf":[{"type":"object","properties":{"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["videoUrl","posterUrl"],"additionalProperties":false},{"type":"null"}]},"animal":{"anyOf":[{"type":"object","properties":{"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["videoUrl","posterUrl"],"additionalProperties":false},{"type":"null"}]}},"required":["fruit","animal"],"additionalProperties":false},{"type":"null"}]},"preview":{"anyOf":[{"type":"object","properties":{"soundOff":{"anyOf":[{"type":"string"},{"type":"null"}]},"steps":{"type":"array","items":{"type":"object","properties":{"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["label","text"],"additionalProperties":false}},"ideas":{"description":"Starter ideas per species.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["soundOff","steps","ideas"],"additionalProperties":false},{"type":"null"}]},"ending":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","label","tagline","kind","species","plans","lengths","defaultLength","look","samples","preview","ending"],"additionalProperties":false}},"required":["format"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"format":{"id":"forehead-number","label":"Number on Forehead","tagline":"Everyone can see your number. Then it changes.","kind":"story","species":["fruit","animal"],"plans":["pro","advanced","enterprise","ultra","legacy"],"lengths":[65,75,85],"defaultLength":75,"look":"classic","samples":{"fruit":{"videoUrl":"https://media.autoclips.app/clips/fruit-formats/forehead-number/sample-fruit.mp4","posterUrl":"https://media.autoclips.app/clips/fruit-formats/forehead-number/poster-fruit.jpg"},"animal":null},"preview":{"soundOff":"Every forehead shows a number everyone believes.","steps":[{"label":"Hook","text":"Two numbers are compared in the first second."}],"ideas":{"fruit":["A poor boy with $5 on his forehead starts at a school where everyone has millions."]}},"ending":null}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/ideas":{"get":{"operationId":"fruit_formats_trending_ideas","summary":"Today's trending Fruit story ideas (the create page's idea chips).","description":"Today's trending Fruit story ideas (the create page's idea chips).\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"fruit.formats.trending_ideas","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_formats action=trending_ideas","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ideas":{"type":"array","items":{"type":"string"}},"generatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ideas","generatedAt"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"ideas":["A cashier is mocked for her old shoes; the shop owner is her father."],"generatedAt":"2026-10-27T06:00:00.000Z"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects":{"get":{"operationId":"fruit_projects_list","summary":"List your Fruit AI or Animal stories, newest first.","description":"Your Fruit AI stories (or, with species animal, your Animal Stories), newest first, up to 50: title, format, stage, the finished video, series part and what each used. A new account sees the demo projects the page shows; they can be read, not changed.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"fruit.projects.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_projects action=list","parameters":[{"name":"species","in":"query","required":false,"schema":{"description":"fruit (default) or animal.","type":"string","enum":["fruit","animal"]},"description":"fruit (default) or animal."},{"name":"limit","in":"query","required":false,"schema":{"description":"How many (1-50, default 20).","type":"integer","minimum":1,"maximum":50},"description":"How many (1-50, default 20).","example":5}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"species":{"type":"string","enum":["fruit","animal"]},"format":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"demo":{"description":"A demo project: it can be read, not changed.","type":"boolean"},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","status"],"additionalProperties":false},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["seriesId","title","partNumber"],"additionalProperties":false},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"creditsUsed":{"type":"number"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","species","format","status","progress","durationSeconds","demo","video","thumbnailUrl","series","characters","creditsUsed","createdAt","appUrl"],"additionalProperties":false}}},"required":["projects"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"projects":[{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","species":"fruit","format":"forehead-number","status":"completed","progress":100,"durationSeconds":75,"demo":false,"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed"},"thumbnailUrl":null,"series":null,"characters":["Mango","Kiwi"],"creditsUsed":2340,"createdAt":"2026-10-27T09:00:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"fruit_story_create","summary":"Start a Fruit AI or Animal story from an idea or a pasted script. Charges the script.","description":"Starts a Fruit AI story (or an Animal Story, species animal) from an idea or, for Fruit AI, a pasted script, with every option of the create page (autoclips_options product fruit). Create charges the script only, as the page does; the story then writes, casts and draws its character looks by itself (a few minutes) and waits at cast_ready. Then: fruit_story approve (the frames), fruit_story continue (the clips), fruit_finish render (free). Or use fruit_story make to do it all in one go. Answers with a job that ends when the story waits for you.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.story.create","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_story action=create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idea":{"description":"Your story idea, 10 to 2000 characters (or send script).","type":"string","maxLength":2000},"script":{"description":"Fruit AI only: your own script to act out, 20 to 1500 characters, instead of an idea.","type":"string","maxLength":1500},"species":{"description":"Fruit or animal: Fruit AI (people with fruit heads) or Animal Stories (photoreal animal heads on people). Animal Stories come only in the story formats, take an idea (not a pasted script) and do not use the fruit character library.\nChoices:\n- fruit — Fruit AI: Fruit-headed people, every format.\n- animal — Animal Stories: Animal-headed people, story formats only.\nDefault: fruit.","type":"string","enum":["fruit","animal"]},"storyFormat":{"description":"Format: The shape of the story. Story formats (65 to 85 seconds, Pro and up) are viral micro-dramas with a world rule and a Part 2 hook; reel formats are the measured 30 to 65 second Fruit comedies; the older formats are kept for those who use them. Animal Stories take a story format only (default secret-identity). fruit_formats get shows a format's example video, beats and default look.\nChoices:\n- forehead-number — Number on Forehead: Story format: Everyone can see your number. Then it changes. (plans: pro, advanced, enterprise, ultra, legacy)\n- million-challenge — Million-Dollar Challenge: Story format: Your worst habit just became worth a million. (plans: pro, advanced, enterprise, ultra, legacy)\n- secret-identity — Secret Identity: Story format: The new kid is quiet. Nobody knows who he really is. (plans: pro, advanced, enterprise, ultra, legacy)\n- plot-twist — Emotional Plot Twist: Story format: A wrong done in plain sight. A twist nobody saw coming. (plans: pro, advanced, enterprise, ultra, legacy)\n- glow-up — Glow-Up Revenge: Story format: They called her a zero. Wait till they see her now. (plans: pro, advanced, enterprise, ultra, legacy)\n- giant-curse — Giant Curse: Story format: One spell made her enormous. Now he has to break it. (plans: pro, advanced, enterprise, ultra, legacy)\n- impossible-commission — Impossible Commission: Story format: A billionaire problem. A $5 builder. One shot. (plans: pro, advanced, enterprise, ultra, legacy)\n- countdown-trap — Countdown Trap: Story format: Ten seconds left. And someone planned this. (plans: pro, advanced, enterprise, ultra, legacy)\n- the-test — The Test: Story format: Two heirs. Three suitors. Only one passes. (plans: pro, advanced, enterprise, ultra, legacy)\n- burger-money — Rich vs Poor: Reel format: The rich one mocks the worker. Then needs them.\n- cheating — Cheating: Reel format: Caught in the act. One lie. One cold verdict.\n- cuh — Cuh: Reel format: Dad picks a favourite. Years later the other one wins.\n- correct-me — Correct Me If I'm Wrong: Reel format: He asks the wrong question. It works anyway.\n- two-paths — Two Child, Two Paths: Reel format: Two babies, two trades, one couch.\n- custom — Custom: Reel format: Your idea or your script, told your way.\n- short-film — Short Film: Classic format: Cinematic mini-movie — widescreen, real camera work. (plans: pro, advanced, enterprise, ultra, legacy)\n- reality-show — Reality Show: Classic format: Love Island style dating drama.\n- comedy — Comedy Sketch: Classic format: Short-form comedy. (plans: pro, advanced, enterprise, ultra, legacy)\n- drama — Drama Series: Classic format: Serialized dramatic storytelling. (plans: pro, advanced, enterprise, ultra, legacy)\n- educational — Educational: Classic format: Fun educational content. (plans: pro, advanced, enterprise, ultra, legacy)\n- music-video — Music Video: Classic format: Performance and dance. (plans: pro, advanced, enterprise, ultra, legacy)\n- cooking-show — Cooking Show: Classic format: Food-related scenarios. (plans: pro, advanced, enterprise, ultra, legacy)\nDefault: forehead-number.","type":"string","enum":["forehead-number","million-challenge","secret-identity","plot-twist","glow-up","giant-curse","impossible-commission","countdown-trap","the-test","burger-money","cheating","cuh","correct-me","two-paths","custom","short-film","reality-show","comedy","drama","educational","music-video","cooking-show"]},"formatAuto":{"description":"Story formats only: the director picks the story format that fits the idea best (storyFormat is the fallback). Default false.","type":"boolean"},"lengthSeconds":{"description":"How long it runs, in seconds: a story format 65, 75 or 85; any other format 30, 38, 46, 54, 60 or 65. Default: the format's own (75 or 46). Over 32 seconds needs Pro or higher.","type":"integer","minimum":20,"maximum":90},"language":{"description":"The language the characters speak (autoclips_options product fruit, option language). Default en.","type":"string","minLength":2,"maxLength":16},"aspectRatio":{"description":"Shape: The video's shape. A series keeps the shape of its Part 1.\nChoices:\n- 9:16 — 9:16: Vertical (TikTok/Reels).\n- 16:9 — 16:9: Horizontal (YouTube).\n- 1:1 — 1:1: Square.\nDefault: 9:16.","type":"string","enum":["9:16","16:9","1:1"]},"chemistry":{"description":"Chemistry: How much romance the couples show. Clothes stay on at every level.\nChoices:\n- clean — Clean: Barely touch. The story is the same.\n- flirty — Flirty: Hugs, an arm round a waist, looks that hold.\n- spicy — Spicy: Kissing and dancing too. Adds a dance track.\nDefault: flirty.","type":"string","enum":["clean","flirty","spicy"]},"look":{"description":"Look: How the cast is dressed. Left out, the format decides (Hot on glow-up, giant-curse and impossible-commission; Classic elsewhere), and an idea about a child or a teenager is always Classic by default. Hot is grown-ups (21+) only and never nudity. A series keeps its look unless a part picks one.\nChoices:\n- classic — Classic: Everyone dressed for the story.\n- hot — Hot: Glamorous grown-up leads: figure-hugging outfits, curves, cleavage. Never nudity.\nDefault: The format's own look (leave it out).","type":"string","enum":["classic","hot"]},"scriptModel":{"description":"Writer: Which AI writes the script. The writer sets the script's price.\nChoices:\n- opus — Claude Opus 5.5: Claude Opus 5.5 writes the script. (300 credits for the script)\n- gemini — Gemini 3.8 Flash: Gemini 3.8 Flash writes the script. (120 credits for the script)\n- muse — Muse Spark 1.3: Muse Spark 1.3 writes the script. (120 credits for the script)\n- kimi — Kimi K3: Kimi K3 writes the script. (200 credits for the script)\n- grok — Grok 4.6: Grok 4.6 writes the script. (110 credits for the script)\nDefault: opus.","type":"string","enum":["opus","gemini","muse","kimi","grok"]},"imageModel":{"description":"Picture model: Which model draws the character looks and the scene frames. It sets each picture's price.\nChoices:\n- nano-banana-2 — Nano Banana 2: Highest quality, best character consistency. (72 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2-high — Precision Max: Sharpest detail and the most literal prompt accuracy. (107 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2 — Precision: Same accuracy at a lower resolution — cheaper per image. (33 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-2-pro — FLUX 2 Pro: Excellent style adherence and detail. (48 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- nano-banana — Nano Banana: Good quality, faster generation. (24 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-kontext-pro — FLUX Kontext Pro: Good balance of quality and speed. (24 credits a picture)\n- flux-kontext-dev — FLUX Kontext Dev: Budget option for testing. (15 credits a picture)\n- krea-2-medium — Krea 2: Stunning aesthetics — style-reference consistency. (25 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\nDefault: nano-banana-2.","type":"string","enum":["nano-banana-2","gpt-image-2-high","gpt-image-2","flux-2-pro","nano-banana","flux-kontext-pro","flux-kontext-dev","krea-2-medium"]},"videoModel":{"description":"Video model: Which model films each scene's talking clip. The four AutoClips models and Reel are on the create page. AutoClips 1 Lite and Lite Full HD speak the lines in each character's voice (set it with the cast's voice option; voices are free). A Short Film is filmed on Cinematic Pro; the others are kept for older stories.\nChoices:\n- autoclips1 — AutoClips 1: Our main model. Strong acting, speaks every line. (12 credits a second of clip)\n- autoclips1Upscaled — AutoClips 1 1080p Upscaled: AutoClips 1, sharpened to 1080p. (16 credits a second of clip)\n- autoclips1Light — AutoClips 1 Lite: Half the price. Lines are spoken in the voices you pick. (6 credits a second of clip)\n- autoclips1LightHd — AutoClips 1 Lite Full HD: AutoClips 1 Lite drawn at full 1080p. (18 credits a second of clip)\n- autoclips — AutoClips 1 1080p Upscaled: The older name for AutoClips 1 1080p Upscaled, kept for saved stories and automations. (16 credits a second of clip)\n- minimax — Reel: Big expressive acting, one clean shot per scene, 10-second clips. (52 credits a second of clip)\n- omniMax — Pro Max: Best quality, fastest generation. (1500 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\n- veo31lite — Lite: Fast and affordable — 720p with audio. (240 credits a clip)\n- klingStd — Cinematic: Multi-shot — several camera angles cut together in one take. (600 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\n- klingPro — Cinematic Pro: Multi-shot at the highest quality tier. (810 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\nDefault: autoclips1.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd","autoclips","minimax","omniMax","veo31lite","klingStd","klingPro"]},"captions":{"description":"Burned-in word-by-word captions. Default true (a silent Short Film has none).","type":"boolean"},"music":{"title":"Background music (Fruit AI Stories and Animal Stories option music)","description":"Background music: The music bed, as \"<shelf>:<track id>\" (fai, popular or v3) or \"none\". Left out: story formats start on a copyright-free sad bed; other formats start with no music.\nOne of 333 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=fruit&option=music) to see them all.\nChoices:\n- none — No music: The story plays with its voices and sound only.\n- fai:fai-batida-funk — Batida Funk: Fruit picks shelf.\n- fai:fai-popular — Popular: Fruit picks shelf.\n- fai:fai-slowed — Slowed: Fruit picks shelf.\n- fai:fai-normal — Normal: Fruit picks shelf.\n- popular:hide-and-sneak — Hide and Sneak: Popular shelf.\n- popular:old-time-circus — Old Time Circus: Popular shelf.\n- popular:lurking-behind — Lurking Behind: Popular shelf.\n- popular:ce-burning-memory — It's Just a Burning Memory: Popular shelf.\n- popular:ce-f-down — F.Down: Popular shelf.\n- popular:ce-school-rooftop — School Rooftop (Bird Sounds): Popular shelf.\n- popular:ce-promise-reprise — Promise (Reprise): Popular shelf.\n- popular:ce-everything-in-its-right-place — Everything In Its Right Place (Instrumental): Popular shelf.\n- popular:ce-six-forty-seven — Six Forty Seven: Popular shelf.\n- popular:ce-numbers — Numbers (Instrumental): Popular shelf.\n- popular:ce-fallen-down — Fallen Down (Panic Room): Popular shelf.\n- popular:ce-char-remix — Char (Remix) Slowed: Popular shelf.\n- popular:ce-empathy — Empathy (Slowed + Reverb): Popular shelf.\n- popular:ce-aleph — ALEPH (Slowed + Reverb): Popular shelf.\n- popular:ce-solitude — Solitude (Slowed): Popular shelf.\n- popular:ce-closed-slowed — Closed (Slowed + Reverb): Popular shelf.\n- popular:ce-silhouette — Silhouette (Slowed Best Part): Popular shelf.\n- popular:ce-country-roads — Take Me Home, Country Roads (Karaoke): Popular shelf.\n- popular:ce-house-rising-sun — The House Of The Rising Sun (Instrumental): Popular shelf.\n- popular:ce-feeling-blue — Feeling Blue: Popular shelf.\n- popular:ce-stargazing — Stargazing (Sped Up): Popular shelf.\n- v3:animals-wildlife-01-wild-kingdom-v1 — Wild Kingdom: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-01-wild-kingdom-v2 — Wild Kingdom: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-02-migration-path-v1 — Migration Path: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-02-migration-path-v2 — Migration Path: Copyright-free shelf, copyright-free.\n…and 303 more.\nDefault: The format's default bed (leave it out).","type":"string"},"narrationMode":{"description":"Spoken or silent (Short Film): Short Film only: spoken (dense dialogue) or silent (no dialogue at all, the story told in pictures). Every other format is spoken. A series keeps it.\nChoices:\n- spoken — Spoken: The characters talk.\n- silent — Silent: Nobody speaks; no captions.\nDefault: spoken.","type":"string","enum":["spoken","silent"]},"videoSpeed":{"description":"Speed: How fast the finished video plays, 1x to 2x in steps of 0.1. Changing it on a finished video needs a new render. Series parts keep the speed of the series unless a part picks one. From 1 to 2 x, in steps of 0.1. Default: 1.","type":"number","minimum":1,"maximum":2,"multipleOf":0.1},"partLabel":{"description":"Story formats: show the \"PART N\" label. Default true.","type":"boolean"},"characterIds":{"description":"Fruit AI only: up to 8 characters from your library (yours, a preset or a public one) to cast. Left out: the writer invents the whole cast.","maxItems":8,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$"}},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{"species":"animal","storyFormat":"secret-identity","idea":"A tired night guard is mocked by the hotel guests; at dawn they learn he owns the hotel.","lengthSeconds":75}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"creditsCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","job","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"drafting","status":"pitch-drafting","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":null,"status":null,"progress":null,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"job":{"id":"job_019a1b2c3d4e5f60718293c7","product":"fruit","kind":"fruit.story","resource":{"type":"fruit_project","id":"5f1e2d3c-4b5a-4968-8776-655443322110"},"status":"queued","step":"Writing the script and casting","progress":null,"result":null,"error":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T09:00:00.000Z","finishedAt":null,"poll_after_seconds":30},"creditsCharged":300}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/make":{"post":{"operationId":"fruit_story_make","summary":"Make a whole Fruit or Animal story in one go, within a spending limit. Answers with a job.","description":"Starts the story like create, then presses every button for you: approves the cast, films every scene and renders the video, redrawing a look or a frame that did not come out (twice at most). Each step is charged as it is made, exactly as on the page, and what does not come out is refunded. What you approve is a spending limit (limitCredits; left out, the most this story can cost), and it is the most the run can be charged: before a step that would take the story past it, the story stops where it is and the job ends with limit_reached, so you can finish it step by step. About 20 to 70 minutes. fruit_projects stop switches it off.\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. The limit is the most Fruit story can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.story.make","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_story action=make","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idea":{"description":"Your story idea, 10 to 2000 characters (or send script).","type":"string","maxLength":2000},"script":{"description":"Fruit AI only: your own script to act out, 20 to 1500 characters, instead of an idea.","type":"string","maxLength":1500},"species":{"description":"Fruit or animal: Fruit AI (people with fruit heads) or Animal Stories (photoreal animal heads on people). Animal Stories come only in the story formats, take an idea (not a pasted script) and do not use the fruit character library.\nChoices:\n- fruit — Fruit AI: Fruit-headed people, every format.\n- animal — Animal Stories: Animal-headed people, story formats only.\nDefault: fruit.","type":"string","enum":["fruit","animal"]},"storyFormat":{"description":"Format: The shape of the story. Story formats (65 to 85 seconds, Pro and up) are viral micro-dramas with a world rule and a Part 2 hook; reel formats are the measured 30 to 65 second Fruit comedies; the older formats are kept for those who use them. Animal Stories take a story format only (default secret-identity). fruit_formats get shows a format's example video, beats and default look.\nChoices:\n- forehead-number — Number on Forehead: Story format: Everyone can see your number. Then it changes. (plans: pro, advanced, enterprise, ultra, legacy)\n- million-challenge — Million-Dollar Challenge: Story format: Your worst habit just became worth a million. (plans: pro, advanced, enterprise, ultra, legacy)\n- secret-identity — Secret Identity: Story format: The new kid is quiet. Nobody knows who he really is. (plans: pro, advanced, enterprise, ultra, legacy)\n- plot-twist — Emotional Plot Twist: Story format: A wrong done in plain sight. A twist nobody saw coming. (plans: pro, advanced, enterprise, ultra, legacy)\n- glow-up — Glow-Up Revenge: Story format: They called her a zero. Wait till they see her now. (plans: pro, advanced, enterprise, ultra, legacy)\n- giant-curse — Giant Curse: Story format: One spell made her enormous. Now he has to break it. (plans: pro, advanced, enterprise, ultra, legacy)\n- impossible-commission — Impossible Commission: Story format: A billionaire problem. A $5 builder. One shot. (plans: pro, advanced, enterprise, ultra, legacy)\n- countdown-trap — Countdown Trap: Story format: Ten seconds left. And someone planned this. (plans: pro, advanced, enterprise, ultra, legacy)\n- the-test — The Test: Story format: Two heirs. Three suitors. Only one passes. (plans: pro, advanced, enterprise, ultra, legacy)\n- burger-money — Rich vs Poor: Reel format: The rich one mocks the worker. Then needs them.\n- cheating — Cheating: Reel format: Caught in the act. One lie. One cold verdict.\n- cuh — Cuh: Reel format: Dad picks a favourite. Years later the other one wins.\n- correct-me — Correct Me If I'm Wrong: Reel format: He asks the wrong question. It works anyway.\n- two-paths — Two Child, Two Paths: Reel format: Two babies, two trades, one couch.\n- custom — Custom: Reel format: Your idea or your script, told your way.\n- short-film — Short Film: Classic format: Cinematic mini-movie — widescreen, real camera work. (plans: pro, advanced, enterprise, ultra, legacy)\n- reality-show — Reality Show: Classic format: Love Island style dating drama.\n- comedy — Comedy Sketch: Classic format: Short-form comedy. (plans: pro, advanced, enterprise, ultra, legacy)\n- drama — Drama Series: Classic format: Serialized dramatic storytelling. (plans: pro, advanced, enterprise, ultra, legacy)\n- educational — Educational: Classic format: Fun educational content. (plans: pro, advanced, enterprise, ultra, legacy)\n- music-video — Music Video: Classic format: Performance and dance. (plans: pro, advanced, enterprise, ultra, legacy)\n- cooking-show — Cooking Show: Classic format: Food-related scenarios. (plans: pro, advanced, enterprise, ultra, legacy)\nDefault: forehead-number.","type":"string","enum":["forehead-number","million-challenge","secret-identity","plot-twist","glow-up","giant-curse","impossible-commission","countdown-trap","the-test","burger-money","cheating","cuh","correct-me","two-paths","custom","short-film","reality-show","comedy","drama","educational","music-video","cooking-show"]},"formatAuto":{"description":"Story formats only: the director picks the story format that fits the idea best (storyFormat is the fallback). Default false.","type":"boolean"},"lengthSeconds":{"description":"How long it runs, in seconds: a story format 65, 75 or 85; any other format 30, 38, 46, 54, 60 or 65. Default: the format's own (75 or 46). Over 32 seconds needs Pro or higher.","type":"integer","minimum":20,"maximum":90},"language":{"description":"The language the characters speak (autoclips_options product fruit, option language). Default en.","type":"string","minLength":2,"maxLength":16},"aspectRatio":{"description":"Shape: The video's shape. A series keeps the shape of its Part 1.\nChoices:\n- 9:16 — 9:16: Vertical (TikTok/Reels).\n- 16:9 — 16:9: Horizontal (YouTube).\n- 1:1 — 1:1: Square.\nDefault: 9:16.","type":"string","enum":["9:16","16:9","1:1"]},"chemistry":{"description":"Chemistry: How much romance the couples show. Clothes stay on at every level.\nChoices:\n- clean — Clean: Barely touch. The story is the same.\n- flirty — Flirty: Hugs, an arm round a waist, looks that hold.\n- spicy — Spicy: Kissing and dancing too. Adds a dance track.\nDefault: flirty.","type":"string","enum":["clean","flirty","spicy"]},"look":{"description":"Look: How the cast is dressed. Left out, the format decides (Hot on glow-up, giant-curse and impossible-commission; Classic elsewhere), and an idea about a child or a teenager is always Classic by default. Hot is grown-ups (21+) only and never nudity. A series keeps its look unless a part picks one.\nChoices:\n- classic — Classic: Everyone dressed for the story.\n- hot — Hot: Glamorous grown-up leads: figure-hugging outfits, curves, cleavage. Never nudity.\nDefault: The format's own look (leave it out).","type":"string","enum":["classic","hot"]},"scriptModel":{"description":"Writer: Which AI writes the script. The writer sets the script's price.\nChoices:\n- opus — Claude Opus 5.5: Claude Opus 5.5 writes the script. (300 credits for the script)\n- gemini — Gemini 3.8 Flash: Gemini 3.8 Flash writes the script. (120 credits for the script)\n- muse — Muse Spark 1.3: Muse Spark 1.3 writes the script. (120 credits for the script)\n- kimi — Kimi K3: Kimi K3 writes the script. (200 credits for the script)\n- grok — Grok 4.6: Grok 4.6 writes the script. (110 credits for the script)\nDefault: opus.","type":"string","enum":["opus","gemini","muse","kimi","grok"]},"imageModel":{"description":"Picture model: Which model draws the character looks and the scene frames. It sets each picture's price.\nChoices:\n- nano-banana-2 — Nano Banana 2: Highest quality, best character consistency. (72 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2-high — Precision Max: Sharpest detail and the most literal prompt accuracy. (107 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2 — Precision: Same accuracy at a lower resolution — cheaper per image. (33 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-2-pro — FLUX 2 Pro: Excellent style adherence and detail. (48 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- nano-banana — Nano Banana: Good quality, faster generation. (24 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-kontext-pro — FLUX Kontext Pro: Good balance of quality and speed. (24 credits a picture)\n- flux-kontext-dev — FLUX Kontext Dev: Budget option for testing. (15 credits a picture)\n- krea-2-medium — Krea 2: Stunning aesthetics — style-reference consistency. (25 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\nDefault: nano-banana-2.","type":"string","enum":["nano-banana-2","gpt-image-2-high","gpt-image-2","flux-2-pro","nano-banana","flux-kontext-pro","flux-kontext-dev","krea-2-medium"]},"videoModel":{"description":"Video model: Which model films each scene's talking clip. The four AutoClips models and Reel are on the create page. AutoClips 1 Lite and Lite Full HD speak the lines in each character's voice (set it with the cast's voice option; voices are free). A Short Film is filmed on Cinematic Pro; the others are kept for older stories.\nChoices:\n- autoclips1 — AutoClips 1: Our main model. Strong acting, speaks every line. (12 credits a second of clip)\n- autoclips1Upscaled — AutoClips 1 1080p Upscaled: AutoClips 1, sharpened to 1080p. (16 credits a second of clip)\n- autoclips1Light — AutoClips 1 Lite: Half the price. Lines are spoken in the voices you pick. (6 credits a second of clip)\n- autoclips1LightHd — AutoClips 1 Lite Full HD: AutoClips 1 Lite drawn at full 1080p. (18 credits a second of clip)\n- autoclips — AutoClips 1 1080p Upscaled: The older name for AutoClips 1 1080p Upscaled, kept for saved stories and automations. (16 credits a second of clip)\n- minimax — Reel: Big expressive acting, one clean shot per scene, 10-second clips. (52 credits a second of clip)\n- omniMax — Pro Max: Best quality, fastest generation. (1500 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\n- veo31lite — Lite: Fast and affordable — 720p with audio. (240 credits a clip)\n- klingStd — Cinematic: Multi-shot — several camera angles cut together in one take. (600 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\n- klingPro — Cinematic Pro: Multi-shot at the highest quality tier. (810 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\nDefault: autoclips1.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd","autoclips","minimax","omniMax","veo31lite","klingStd","klingPro"]},"captions":{"description":"Burned-in word-by-word captions. Default true (a silent Short Film has none).","type":"boolean"},"music":{"title":"Background music (Fruit AI Stories and Animal Stories option music)","description":"Background music: The music bed, as \"<shelf>:<track id>\" (fai, popular or v3) or \"none\". Left out: story formats start on a copyright-free sad bed; other formats start with no music.\nOne of 333 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=fruit&option=music) to see them all.\nChoices:\n- none — No music: The story plays with its voices and sound only.\n- fai:fai-batida-funk — Batida Funk: Fruit picks shelf.\n- fai:fai-popular — Popular: Fruit picks shelf.\n- fai:fai-slowed — Slowed: Fruit picks shelf.\n- fai:fai-normal — Normal: Fruit picks shelf.\n- popular:hide-and-sneak — Hide and Sneak: Popular shelf.\n- popular:old-time-circus — Old Time Circus: Popular shelf.\n- popular:lurking-behind — Lurking Behind: Popular shelf.\n- popular:ce-burning-memory — It's Just a Burning Memory: Popular shelf.\n- popular:ce-f-down — F.Down: Popular shelf.\n- popular:ce-school-rooftop — School Rooftop (Bird Sounds): Popular shelf.\n- popular:ce-promise-reprise — Promise (Reprise): Popular shelf.\n- popular:ce-everything-in-its-right-place — Everything In Its Right Place (Instrumental): Popular shelf.\n- popular:ce-six-forty-seven — Six Forty Seven: Popular shelf.\n- popular:ce-numbers — Numbers (Instrumental): Popular shelf.\n- popular:ce-fallen-down — Fallen Down (Panic Room): Popular shelf.\n- popular:ce-char-remix — Char (Remix) Slowed: Popular shelf.\n- popular:ce-empathy — Empathy (Slowed + Reverb): Popular shelf.\n- popular:ce-aleph — ALEPH (Slowed + Reverb): Popular shelf.\n- popular:ce-solitude — Solitude (Slowed): Popular shelf.\n- popular:ce-closed-slowed — Closed (Slowed + Reverb): Popular shelf.\n- popular:ce-silhouette — Silhouette (Slowed Best Part): Popular shelf.\n- popular:ce-country-roads — Take Me Home, Country Roads (Karaoke): Popular shelf.\n- popular:ce-house-rising-sun — The House Of The Rising Sun (Instrumental): Popular shelf.\n- popular:ce-feeling-blue — Feeling Blue: Popular shelf.\n- popular:ce-stargazing — Stargazing (Sped Up): Popular shelf.\n- v3:animals-wildlife-01-wild-kingdom-v1 — Wild Kingdom: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-01-wild-kingdom-v2 — Wild Kingdom: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-02-migration-path-v1 — Migration Path: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-02-migration-path-v2 — Migration Path: Copyright-free shelf, copyright-free.\n…and 303 more.\nDefault: The format's default bed (leave it out).","type":"string"},"narrationMode":{"description":"Spoken or silent (Short Film): Short Film only: spoken (dense dialogue) or silent (no dialogue at all, the story told in pictures). Every other format is spoken. A series keeps it.\nChoices:\n- spoken — Spoken: The characters talk.\n- silent — Silent: Nobody speaks; no captions.\nDefault: spoken.","type":"string","enum":["spoken","silent"]},"videoSpeed":{"description":"Speed: How fast the finished video plays, 1x to 2x in steps of 0.1. Changing it on a finished video needs a new render. Series parts keep the speed of the series unless a part picks one. From 1 to 2 x, in steps of 0.1. Default: 1.","type":"number","minimum":1,"maximum":2,"multipleOf":0.1},"partLabel":{"description":"Story formats: show the \"PART N\" label. Default true.","type":"boolean"},"characterIds":{"description":"Fruit AI only: up to 8 characters from your library (yours, a preset or a public one) to cast. Left out: the writer invents the whole cast.","maxItems":8,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$"}},"limitCredits":{"description":"The most this story may spend in all, in credits. Left out: the most it can cost (fruit_story quote creditsAtMost).","type":"integer","minimum":1,"maximum":100000},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"additionalProperties":false},"example":{"storyFormat":"glow-up","idea":"A shy cleaner is laughed at by the whole office; at midnight her forehead number changes.","limitCredits":3000}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"limitCredits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","job","limitCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"drafting","status":"pitch-drafting","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":{"on":true,"limitCredits":3000,"state":"running","message":null},"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"job":{"id":"job_019a1b2c3d4e5f60718293c8","product":"fruit","kind":"fruit.story","resource":{"type":"fruit_project","id":"5f1e2d3c-4b5a-4968-8776-655443322110"},"status":"queued","step":"Making the whole story","progress":null,"result":null,"error":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T09:00:00.000Z","finishedAt":null,"poll_after_seconds":30},"limitCredits":3000}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}":{"get":{"operationId":"fruit_projects_get","summary":"Read one Fruit or Animal story: its stage, what waits for you, script, cast, frames, clips, video and prices.","description":"One story in full. stage says where it is and nextAction what waits for you (select_script, make_looks, approve, continue, render or retry); pricing says what each next step costs right now, the same figures the page shows.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"fruit.projects.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_projects action=get","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false}},"required":["project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/approve":{"post":{"operationId":"fruit_story_approve","summary":"Approve the cast and draw every scene's frame. Charges the frames.","description":"For a story at cast_ready: approves the script and the cast and draws one frame per scene (and the close-ups a reel format plans). Charged per frame at the picture model's price, as the page does; a frame that does not come out is refunded. The story then waits at frames_ready for continue. Answers with a job.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.story.approve","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_story action=approve","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"creditsCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","job","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"drawing_frames","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"job":{"id":"job_019a1b2c3d4e5f60718293c9","product":"fruit","kind":"fruit.story","resource":{"type":"fruit_project","id":"5f1e2d3c-4b5a-4968-8776-655443322110"},"status":"queued","step":"Drawing the frames","progress":null,"result":null,"error":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T09:00:00.000Z","finishedAt":null,"poll_after_seconds":30},"creditsCharged":576}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/cast":{"post":{"operationId":"fruit_cast_add","summary":"Add a cast member: a library character (free) or a new one (charges its look).","description":"Adds a character to the story's cast. A library character (yours, a preset or a public one; Fruit AI only) costs nothing (it counts toward the free-AI daily limit); a new character is drawn once, at one picture's price, refunded if it does not come out. Then use them in the script with fruit_edit.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.cast.add","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_cast action=add","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"characterId":{"description":"A library character (fruit_characters list).","type":"string","pattern":"^[a-f0-9]{24}$"},"newCharacter":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"kind":{"description":"The fruit (Fruit AI) or the animal (Animal Stories) of their head.","type":"string","minLength":1,"maxLength":40},"gender":{"description":"Default female (session-cast.js).","type":"string","enum":["female","male"]},"age":{"type":"integer","minimum":1,"maximum":99},"personality":{"type":"string","maxLength":300},"outfit":{"type":"string","maxLength":300}},"required":["name","kind"],"additionalProperties":false},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{"newCharacter":{"name":"Papaya","kind":"papaya","gender":"female","age":30}}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","castId","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"castId":"cast-5","creditsCharged":72}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/cast/looks":{"post":{"operationId":"fruit_cast_make_looks","summary":"Draw every character look still missing (after a look failed). Charges one picture a look.","description":"For a story at cast_ready whose looks did not all come out: gives back the failed ones and draws every missing look again, one picture each at the picture model's price. A look that does not come out is refunded. Answers with a job.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.cast.make_looks","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_cast action=make_looks","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"creditsCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","job","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"cast_ready","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"job":{"id":"job_019a1b2c3d4e5f60718293cb","product":"fruit","kind":"fruit.story","resource":{"type":"fruit_project","id":"5f1e2d3c-4b5a-4968-8776-655443322110"},"status":"queued","step":"Drawing the looks","progress":null,"result":null,"error":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T09:00:00.000Z","finishedAt":null,"poll_after_seconds":30},"creditsCharged":72}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/cast/{castId}":{"patch":{"operationId":"fruit_cast_update","summary":"Rename or change a cast member (free).","description":"Changes a cast member's name (carried through the script), personality, gender, age, outfit or, for a new character, their fruit or animal. A change to how they look needs the look redrawn (lookNeedsRender: fruit_cast regenerate_look).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.cast.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_cast action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"personality":{"type":"string","maxLength":300},"gender":{"description":"Default female (session-cast.js).","type":"string","enum":["female","male"]},"age":{"type":"integer","minimum":1,"maximum":99},"kind":{"type":"string","minLength":1,"maxLength":40},"outfit":{"type":"string","maxLength":300}},"additionalProperties":false},"example":{"name":"Mango Mia"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"castId","in":"path","required":true,"schema":{"description":"The cast member (project.cast[].castId).","type":"string","minLength":1,"maxLength":60},"description":"The cast member (project.cast[].castId).","example":"cast-1"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"lookNeedsRender":{"type":"boolean"}},"required":["project","lookNeedsRender"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"lookNeedsRender":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"fruit_cast_remove","summary":"Take a cast member out of the story (free; refused while a scene uses them).","description":"Take a cast member out of the story (free; refused while a scene uses them).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.cast.remove","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_cast action=remove","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"castId","in":"path","required":true,"schema":{"description":"The cast member (project.cast[].castId).","type":"string","minLength":1,"maxLength":60},"description":"The cast member (project.cast[].castId).","example":"cast-5"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false}},"required":["project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/cast/{castId}/looks/{lookKey}":{"post":{"operationId":"fruit_cast_regenerate_look","summary":"Redraw one character look, optionally with a change. Charges one picture.","description":"Redraws one look of one cast member (with change: as you describe it). One picture at the picture model's price; refunded if it does not come out. Frames already drawn keep the old look until they are redrawn. Read the new look with fruit_projects get.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.cast.regenerate_look","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_cast action=regenerate_look","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"change":{"description":"What to change, in your words (\"make her hair red\"). Left out: drawn again as planned.","type":"string","minLength":1,"maxLength":500},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{"change":"a red evening dress"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"castId","in":"path","required":true,"schema":{"description":"The cast member (project.cast[].castId).","type":"string","minLength":1,"maxLength":60},"description":"The cast member (project.cast[].castId).","example":"cast-1"},{"name":"lookKey","in":"path","required":true,"schema":{"description":"The look (project.cast[].looks[].lookKey).","type":"string","minLength":1,"maxLength":60},"description":"The look (project.cast[].looks[].lookKey).","example":"default"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"creditsCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"creditsCharged":72}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/cast/{castId}/sheet":{"post":{"operationId":"fruit_cast_sheet","summary":"Draw a cast member's character sheet (their reference angles), optionally saved to your library. Charges one picture an angle.","description":"Draw a cast member's character sheet (their reference angles), optionally saved to your library. Charges one picture an angle.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.cast.sheet","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_cast action=sheet","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"saveToLibrary":{"description":"Also keep the sheet on the library character they came from.","type":"boolean"},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"castId","in":"path","required":true,"schema":{"description":"The cast member (project.cast[].castId).","type":"string","minLength":1,"maxLength":60},"description":"The cast member (project.cast[].castId).","example":"cast-1"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"generated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"creditsCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","generated","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"generated":1,"creditsCharged":72}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/cast/{castId}/voice":{"put":{"operationId":"fruit_cast_set_voice","summary":"Pick the voice a cast member speaks in on AutoClips 1 Lite (free).","description":"AutoClips 1 Lite and Lite Full HD speak every line in the cast's voices. Give a voice id from autoclips_voices (a library voice or one of your own clones), or null for the automatic voice, which stays the same in every scene. The other video models make their own voices and ignore this. Your own saved character keeps the voice for its next story.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.cast.set_voice","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_cast action=set_voice","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"voiceId":{"anyOf":[{"type":"string","pattern":"^[A-Za-z0-9]{8,64}$"},{"type":"null"}]},"voiceName":{"type":"string","maxLength":60}},"required":["voiceId"],"additionalProperties":false},"example":{"voiceId":"EXAVITQu4vr4xnSDxMaL","voiceName":"Sarah"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"castId","in":"path","required":true,"schema":{"description":"The cast member (project.cast[].castId).","type":"string","minLength":1,"maxLength":60},"description":"The cast member (project.cast[].castId).","example":"cast-1"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false}},"required":["project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/continue":{"post":{"operationId":"fruit_story_continue","summary":"Film every scene from its frame. Charges the clips.","description":"For a story at frames_ready: films every scene's talking clip. Charged per clip at the video model's price (per second on AutoClips and Reel), as the page does; a clip that does not come out is refunded. The timeline is then built by itself and the story waits at ready_to_render for fruit_finish render. Answers with a job (about 5 to 30 minutes).\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.story.continue","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_story action=continue","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"creditsCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","job","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"filming","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"job":{"id":"job_019a1b2c3d4e5f60718293ca","product":"fruit","kind":"fruit.story","resource":{"type":"fruit_project","id":"5f1e2d3c-4b5a-4968-8776-655443322110"},"status":"queued","step":"Filming the scenes","progress":null,"result":null,"error":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T09:00:00.000Z","finishedAt":null,"poll_after_seconds":30},"creditsCharged":1260}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/finish":{"patch":{"operationId":"fruit_finish_update","summary":"Change captions, music, its volume, the end card or the speed (free). Render again to see it.","description":"Changes how the finished video looks and sounds: captions on or off and their look, the music bed (an id from autoclips_options product fruit option music, or \"none\") and its volume, your end card (an outro id from autoclips_outros; a paid plan), and the speed (1 to 2). Free. Turning captions on for a story that had none times its words first. Render again (render, free) to see it.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.finish.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_finish action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"captions":{"type":"boolean"},"captionStyle":{"description":"The caption look, the keys the Video step sets (font, size, colours, position...). Unknown keys are refused.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string","maxLength":60},{"type":"number"},{"type":"boolean"}]}},"music":{"title":"Background music (Fruit AI Stories and Animal Stories option music)","description":"Background music: The music bed, as \"<shelf>:<track id>\" (fai, popular or v3) or \"none\". Left out: story formats start on a copyright-free sad bed; other formats start with no music.\nOne of 333 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=fruit&option=music) to see them all.\nChoices:\n- none — No music: The story plays with its voices and sound only.\n- fai:fai-batida-funk — Batida Funk: Fruit picks shelf.\n- fai:fai-popular — Popular: Fruit picks shelf.\n- fai:fai-slowed — Slowed: Fruit picks shelf.\n- fai:fai-normal — Normal: Fruit picks shelf.\n- popular:hide-and-sneak — Hide and Sneak: Popular shelf.\n- popular:old-time-circus — Old Time Circus: Popular shelf.\n- popular:lurking-behind — Lurking Behind: Popular shelf.\n- popular:ce-burning-memory — It's Just a Burning Memory: Popular shelf.\n- popular:ce-f-down — F.Down: Popular shelf.\n- popular:ce-school-rooftop — School Rooftop (Bird Sounds): Popular shelf.\n- popular:ce-promise-reprise — Promise (Reprise): Popular shelf.\n- popular:ce-everything-in-its-right-place — Everything In Its Right Place (Instrumental): Popular shelf.\n- popular:ce-six-forty-seven — Six Forty Seven: Popular shelf.\n- popular:ce-numbers — Numbers (Instrumental): Popular shelf.\n- popular:ce-fallen-down — Fallen Down (Panic Room): Popular shelf.\n- popular:ce-char-remix — Char (Remix) Slowed: Popular shelf.\n- popular:ce-empathy — Empathy (Slowed + Reverb): Popular shelf.\n- popular:ce-aleph — ALEPH (Slowed + Reverb): Popular shelf.\n- popular:ce-solitude — Solitude (Slowed): Popular shelf.\n- popular:ce-closed-slowed — Closed (Slowed + Reverb): Popular shelf.\n- popular:ce-silhouette — Silhouette (Slowed Best Part): Popular shelf.\n- popular:ce-country-roads — Take Me Home, Country Roads (Karaoke): Popular shelf.\n- popular:ce-house-rising-sun — The House Of The Rising Sun (Instrumental): Popular shelf.\n- popular:ce-feeling-blue — Feeling Blue: Popular shelf.\n- popular:ce-stargazing — Stargazing (Sped Up): Popular shelf.\n- v3:animals-wildlife-01-wild-kingdom-v1 — Wild Kingdom: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-01-wild-kingdom-v2 — Wild Kingdom: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-02-migration-path-v1 — Migration Path: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-02-migration-path-v2 — Migration Path: Copyright-free shelf, copyright-free.\n…and 303 more.\nDefault: The format's default bed (leave it out).","type":"string"},"musicVolume":{"description":"Music volume: How loud the music bed plays under the voices, in percent. From 0 to 100 percent. Default: The house level (leave it out).","type":"integer","minimum":0,"maximum":100},"endCard":{"description":"Your end card, or \"none\".","anyOf":[{"type":"object","properties":{"outroId":{"description":"Your outro (autoclips_outros list).","type":"string","minLength":1,"maxLength":80}},"required":["outroId"],"additionalProperties":false},{"type":"string","const":"none"}]},"videoSpeed":{"description":"Speed: How fast the finished video plays, 1x to 2x in steps of 0.1. Changing it on a finished video needs a new render. Series parts keep the speed of the series unless a part picks one. From 1 to 2 x, in steps of 0.1. Default: 1.","type":"number","minimum":1,"maximum":2,"multipleOf":0.1}},"additionalProperties":false},"example":{"music":"none","videoSpeed":1.2}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false}},"required":["project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/locations/{slot}":{"post":{"operationId":"fruit_cast_regenerate_location","summary":"Redraw one place, optionally with a change. Charges one picture.","description":"Redraw one place, optionally with a change. Charges one picture.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.cast.regenerate_location","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_cast action=regenerate_location","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"change":{"description":"What to change, in your words (\"make her hair red\"). Left out: drawn again as planned.","type":"string","minLength":1,"maxLength":500},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{"change":"at night, neon lights"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"slot","in":"path","required":true,"schema":{"description":"The place (project.locations[].slot).","type":"string","pattern":"^(loc-[1-6]|primary|secondary)$"},"description":"The place (project.locations[].slot).","example":"loc-1"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"creditsCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"creditsCharged":72}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/post-text":{"post":{"operationId":"fruit_finish_post_text","summary":"The post's title, description and hashtags (written once, free; writing them again counts toward the free-AI daily limit).","description":"The post's title, description and hashtags (written once, free; writing them again counts toward the free-AI daily limit).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.finish.post_text","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_finish action=post_text","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rewrite":{"description":"Write them again (default false: the ones written already).","type":"boolean"}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"title":"He had $5. They had millions.","description":"Part 1 of 3.","hashtags":["#fruitai","#story"]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/render":{"post":{"operationId":"fruit_finish_render","summary":"Render the story's video (free). Answers with a job.","description":"Renders the video from the story's timeline with its captions, music, end card and speed. Free; counts toward the finishing daily limit. A story already rendering answers 409. Each render is kept as a version (select_version). Usually 2 to 6 minutes.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.finish.render","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_finish action=render","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false}},"required":["project","job"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"rendering","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"job":{"id":"job_019a1b2c3d4e5f60718293cc","product":"fruit","kind":"fruit.story","resource":{"type":"fruit_project","id":"5f1e2d3c-4b5a-4968-8776-655443322110"},"status":"queued","step":"Rendering the video","progress":null,"result":null,"error":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T09:00:00.000Z","finishedAt":null,"poll_after_seconds":30}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/render/cancel":{"post":{"operationId":"fruit_finish_cancel_render","summary":"Stop a render; the story keeps the video it had (or waits at ready_to_render).","description":"Stop a render; the story keeps the video it had (or waits at ready_to_render).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.finish.cancel_render","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_finish action=cancel_render","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"wasRendering":{"type":"boolean"}},"required":["project","wasRendering"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"wasRendering":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/render/select":{"post":{"operationId":"fruit_finish_select_version","summary":"Make an earlier render the story's video (free).","description":"Make an earlier render the story's video (free).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.finish.select_version","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_finish action=select_version","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"videoUrl":{"description":"One of video.versions[].url (fruit_projects get).","type":"string","maxLength":2048,"format":"uri"}},"required":["videoUrl"],"additionalProperties":false},"example":{"videoUrl":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story_1.mp4"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false}},"required":["project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/retry":{"post":{"operationId":"fruit_projects_retry","summary":"Carry on a story that stopped, from the step it stopped at.","description":"Carries on a failed story from where it stopped. The step it makes again is charged at what it makes (the script, the frames or the clips); a step that was never refunded is not charged again. Answers with a job.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.projects.retry","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_projects action=retry","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false}},"required":["project","job"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"drawing_frames","status":"generating-images","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":null,"status":null,"progress":null,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"job":{"id":"job_019a1b2c3d4e5f60718293c7","product":"fruit","kind":"fruit.story","resource":{"type":"fruit_project","id":"5f1e2d3c-4b5a-4968-8776-655443322110"},"status":"queued","step":"Carrying on","progress":null,"result":null,"error":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T09:00:00.000Z","finishedAt":null,"poll_after_seconds":30}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/scenes/{sceneNumber}/clip":{"post":{"operationId":"fruit_clips_regenerate","summary":"Film one scene's clip again, optionally with a change. Charges one clip.","description":"Films one scene again from its frame (with change: as you describe it) and keeps the new take active; the old take stays as a candidate. One clip at the video model's price, refunded if it does not come out. Takes up to a few minutes; the answer comes when it is done. Render again to see it in the video (fruit_finish render, free).\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.clips.regenerate","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_clips action=regenerate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"change":{"description":"What to change, in your words (\"she looks shocked, hand over her mouth\"). Left out: made again as written.","type":"string","minLength":1,"maxLength":500},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"sceneNumber","in":"path","required":true,"schema":{"description":"The scene's number as the story lists it (script.scenes[].sceneNumber; the first scene is 0).","type":"integer","minimum":0,"maximum":20},"description":"The scene's number as the story lists it (script.scenes[].sceneNumber; the first scene is 0).","example":2},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"clipUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","clipUrl","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"clipUrl":"https://media.autoclips.app/fruit/clip-3.mp4","creditsCharged":140}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/scenes/{sceneNumber}/clip/fix-dialog":{"post":{"operationId":"fruit_clips_fix_dialog","summary":"Fix a clip whose spoken words came out wrong: checks it, then redoes the frame and clip up to twice. Charges only the redos.","description":"Checks the scene's clip against its script. A clip that is right already costs nothing (the check counts toward the free-AI daily limit). Otherwise it redraws the frame and films the clip again, up to twice, each redo charged at one picture plus one clip (what you approve is two redos at most); a redo that fails is refunded, one that comes out still wrong is not. Takes several minutes; the answer comes when it is done.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.clips.fix_dialog","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_clips action=fix_dialog","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"sceneNumber","in":"path","required":true,"schema":{"description":"The scene's number as the story lists it (script.scenes[].sceneNumber; the first scene is 0).","type":"integer","minimum":0,"maximum":20},"description":"The scene's number as the story lists it (script.scenes[].sceneNumber; the first scene is 0).","example":2},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"alreadyCorrect":{"type":"boolean"},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clipUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","alreadyCorrect","attempts","clipUrl","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"alreadyCorrect":false,"attempts":1,"clipUrl":"https://media.autoclips.app/fruit/clip-3b.mp4","creditsCharged":212}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/scenes/{sceneNumber}/clip/select":{"post":{"operationId":"fruit_clips_select_candidate","summary":"Keep an earlier take of a scene (free).","description":"Keep an earlier take of a scene (free).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.clips.select_candidate","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_clips action=select_candidate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"candidateIndex":{"description":"Which take, 0 = the first (script.scenes[].clip.candidates says how many).","type":"integer","minimum":0,"maximum":50}},"required":["candidateIndex"],"additionalProperties":false},"example":{"candidateIndex":0}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"sceneNumber","in":"path","required":true,"schema":{"description":"The scene's number as the story lists it (script.scenes[].sceneNumber; the first scene is 0).","type":"integer","minimum":0,"maximum":20},"description":"The scene's number as the story lists it (script.scenes[].sceneNumber; the first scene is 0).","example":2},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false}},"required":["project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/scenes/{sceneNumber}/frame":{"post":{"operationId":"fruit_frames_regenerate","summary":"Redraw one scene's frame, optionally with a change. Charges one picture (or nothing for a free remake).","description":"Redraws one scene's frame (with change: as you describe it). One picture at the picture model's price, refunded if it does not come out; free when the page offers a free remake of that frame. Its clip is filmed again only when you ask (fruit_clips regenerate), or by continue for a story at frames_ready.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.frames.regenerate","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_frames action=regenerate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"change":{"description":"What to change, in your words (\"she looks shocked, hand over her mouth\"). Left out: made again as written.","type":"string","minLength":1,"maxLength":500},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{"change":"she looks shocked, a hand over her mouth"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"sceneNumber","in":"path","required":true,"schema":{"description":"The scene's number as the story lists it (script.scenes[].sceneNumber; the first scene is 0).","type":"integer","minimum":0,"maximum":20},"description":"The scene's number as the story lists it (script.scenes[].sceneNumber; the first scene is 0).","example":2},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"frameUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","frameUrl","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"frameUrl":"https://media.autoclips.app/fruit/frame-3.jpg","creditsCharged":72}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/scenes/{sceneNumber}/frame/select":{"post":{"operationId":"fruit_frames_select_version","summary":"Go back to an earlier frame of a scene (free).","description":"Go back to an earlier frame of a scene (free).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.frames.select_version","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_frames action=select_version","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"versionIndex":{"description":"Which frame, 0 = the first one drawn (script.scenes[].frame.versions says how many).","type":"integer","minimum":0,"maximum":50}},"required":["versionIndex"],"additionalProperties":false},"example":{"versionIndex":0}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"sceneNumber","in":"path","required":true,"schema":{"description":"The scene's number as the story lists it (script.scenes[].sceneNumber; the first scene is 0).","type":"integer","minimum":0,"maximum":20},"description":"The scene's number as the story lists it (script.scenes[].sceneNumber; the first scene is 0).","example":2},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false}},"required":["project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/script":{"put":{"operationId":"fruit_edit_update_script","summary":"Save your own edits to the script (free).","description":"Saves the whole script you send: title, logline and every scene's lines (at most 6 a scene, 160 characters a line), emotions, places and props. Start from fruit_projects get (script.scenes) and change what you want. Free. Scenes whose words changed get their frames marked to redraw; the answer lists them and any warnings.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.edit.update_script","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_edit action=update_script","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":80},"logline":{"type":"string","maxLength":300},"scenes":{"minItems":1,"maxItems":12,"type":"array","items":{"type":"object","properties":{"sceneNumber":{"type":"integer","minimum":0,"maximum":20},"characters":{"maxItems":8,"type":"array","items":{"type":"string","maxLength":60}},"dialogue":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"characterName":{"type":"string","minLength":1,"maxLength":60},"line":{"type":"string","minLength":1,"maxLength":160},"emotion":{"type":"string","maxLength":40},"action":{"type":"string","maxLength":300},"addressee":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}]},"toCamera":{"type":"boolean"},"cueSound":{"anyOf":[{"type":"string","enum":["doorbell","knock","phone","horn"]},{"type":"null"}]}},"required":["characterName","line"],"additionalProperties":{}}},"location":{"type":"string","maxLength":200},"sceneDescription":{"type":"string","maxLength":1200},"staging":{"type":"string","maxLength":1200},"keyProps":{"maxItems":6,"type":"array","items":{"type":"string","maxLength":80}},"captionWord":{"type":"string","maxLength":40}},"required":["sceneNumber","dialogue"],"additionalProperties":{}}}},"required":["title","scenes"],"additionalProperties":false},"example":{"title":"The $5 Boy","scenes":[{"sceneNumber":0,"dialogue":[{"characterName":"Mango","line":"Five dollars? Is that a joke?"}]}]}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"changedScenes":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"warnings":{"type":"array","items":{"type":"string"}}},"required":["project","changedScenes","warnings"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"changedScenes":[0],"warnings":[]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/script/rewrite":{"post":{"operationId":"fruit_edit_rewrite","summary":"Rewrite the script: describe a change, or ask for a fresh take. Charges the writer's price.","description":"The story's own writer writes the script again: with change, as you describe it (\"make the ending sadder\", \"she says no in scene 4\"); without, a fresh take. Charged at the writer's price (the same as the first draft), refunded if it fails. It runs in the background (about a minute); read the new script with fruit_projects get. Only while the script can still change.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.edit.rewrite","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_edit action=rewrite","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"change":{"description":"What to change, in your words. Left out: a fresh take.","type":"string","minLength":3,"maxLength":600},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{"change":"make the ending sadder"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"creditsCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"creditsCharged":300}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/script/select":{"post":{"operationId":"fruit_story_select_script","summary":"Pick one of the drafted scripts (a story waiting at choosing_script).","description":"Free. A story that drafted several scripts (older stories) waits at choosing_script: pick one by its variantId (fruit_projects get scriptOptions). The story then casts itself and waits at cast_ready.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.story.select_script","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_story action=select_script","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"variantId":{"description":"The script to keep (scriptOptions[].variantId).","type":"string","minLength":1,"maxLength":80}},"required":["variantId"],"additionalProperties":false},"example":{"variantId":"a1b2c3"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false}},"required":["project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"casting","status":"generating-cast-plan","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/series":{"post":{"operationId":"fruit_series_from_project","summary":"\"Create Part 2\": make a finished story Part 1 of a new series (free). Then next_part makes Part 2.","description":"Turns a finished story into Part 1 of a series: its cast is locked in as real characters (same faces and voices in every part) and what happened, with its cliffhanger, is written into the series' memory. Free; counts toward the free-AI daily limit. A story already in a series answers with that series (created false). 409 not_finished for a story that is not finished.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.series.from_project","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_series action=from_project","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"A finished story (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"A finished story (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"seriesId":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextPartNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created":{"type":"boolean"}},"required":["seriesId","title","nextPartNumber","created"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"seriesId":"ser_6a1b2c3d","title":"The $5 Boy","nextPartNumber":2,"created":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/projects/{projectId}/stop":{"post":{"operationId":"fruit_projects_stop","summary":"Stop a story being made by fruit_story make; it is kept as far as it got.","description":"Switches the story's autopilot off: no later step is started or charged. A step already running finishes (what does not come out is refunded). Carry on step by step with fruit_story approve and continue and fruit_finish render, or on the page.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.projects.stop","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_projects action=stop","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The story's id (fruit_projects list).","type":"string","minLength":1,"maxLength":80},"description":"The story's id (fruit_projects list).","example":"5f1e2d3c-4b5a-4968-8776-655443322110"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"stopped":{"description":"False when its autopilot was not on.","type":"boolean"}},"required":["project","stopped"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"completed","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"stopped":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/quote":{"post":{"operationId":"fruit_story_quote","summary":"What a Fruit or Animal story with these settings costs: now, about in all, and at most.","description":"Free. Checks the settings the way create does (plan, format, length, models, characters) and answers with every setting filled in, the price create charges now (the script), the page's estimate of the whole story, and the most make could spend on it.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"fruit.story.quote","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_story action=quote","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idea":{"description":"Your story idea, 10 to 2000 characters (or send script).","type":"string","maxLength":2000},"script":{"description":"Fruit AI only: your own script to act out, 20 to 1500 characters, instead of an idea.","type":"string","maxLength":1500},"species":{"description":"Fruit or animal: Fruit AI (people with fruit heads) or Animal Stories (photoreal animal heads on people). Animal Stories come only in the story formats, take an idea (not a pasted script) and do not use the fruit character library.\nChoices:\n- fruit — Fruit AI: Fruit-headed people, every format.\n- animal — Animal Stories: Animal-headed people, story formats only.\nDefault: fruit.","type":"string","enum":["fruit","animal"]},"storyFormat":{"description":"Format: The shape of the story. Story formats (65 to 85 seconds, Pro and up) are viral micro-dramas with a world rule and a Part 2 hook; reel formats are the measured 30 to 65 second Fruit comedies; the older formats are kept for those who use them. Animal Stories take a story format only (default secret-identity). fruit_formats get shows a format's example video, beats and default look.\nChoices:\n- forehead-number — Number on Forehead: Story format: Everyone can see your number. Then it changes. (plans: pro, advanced, enterprise, ultra, legacy)\n- million-challenge — Million-Dollar Challenge: Story format: Your worst habit just became worth a million. (plans: pro, advanced, enterprise, ultra, legacy)\n- secret-identity — Secret Identity: Story format: The new kid is quiet. Nobody knows who he really is. (plans: pro, advanced, enterprise, ultra, legacy)\n- plot-twist — Emotional Plot Twist: Story format: A wrong done in plain sight. A twist nobody saw coming. (plans: pro, advanced, enterprise, ultra, legacy)\n- glow-up — Glow-Up Revenge: Story format: They called her a zero. Wait till they see her now. (plans: pro, advanced, enterprise, ultra, legacy)\n- giant-curse — Giant Curse: Story format: One spell made her enormous. Now he has to break it. (plans: pro, advanced, enterprise, ultra, legacy)\n- impossible-commission — Impossible Commission: Story format: A billionaire problem. A $5 builder. One shot. (plans: pro, advanced, enterprise, ultra, legacy)\n- countdown-trap — Countdown Trap: Story format: Ten seconds left. And someone planned this. (plans: pro, advanced, enterprise, ultra, legacy)\n- the-test — The Test: Story format: Two heirs. Three suitors. Only one passes. (plans: pro, advanced, enterprise, ultra, legacy)\n- burger-money — Rich vs Poor: Reel format: The rich one mocks the worker. Then needs them.\n- cheating — Cheating: Reel format: Caught in the act. One lie. One cold verdict.\n- cuh — Cuh: Reel format: Dad picks a favourite. Years later the other one wins.\n- correct-me — Correct Me If I'm Wrong: Reel format: He asks the wrong question. It works anyway.\n- two-paths — Two Child, Two Paths: Reel format: Two babies, two trades, one couch.\n- custom — Custom: Reel format: Your idea or your script, told your way.\n- short-film — Short Film: Classic format: Cinematic mini-movie — widescreen, real camera work. (plans: pro, advanced, enterprise, ultra, legacy)\n- reality-show — Reality Show: Classic format: Love Island style dating drama.\n- comedy — Comedy Sketch: Classic format: Short-form comedy. (plans: pro, advanced, enterprise, ultra, legacy)\n- drama — Drama Series: Classic format: Serialized dramatic storytelling. (plans: pro, advanced, enterprise, ultra, legacy)\n- educational — Educational: Classic format: Fun educational content. (plans: pro, advanced, enterprise, ultra, legacy)\n- music-video — Music Video: Classic format: Performance and dance. (plans: pro, advanced, enterprise, ultra, legacy)\n- cooking-show — Cooking Show: Classic format: Food-related scenarios. (plans: pro, advanced, enterprise, ultra, legacy)\nDefault: forehead-number.","type":"string","enum":["forehead-number","million-challenge","secret-identity","plot-twist","glow-up","giant-curse","impossible-commission","countdown-trap","the-test","burger-money","cheating","cuh","correct-me","two-paths","custom","short-film","reality-show","comedy","drama","educational","music-video","cooking-show"]},"formatAuto":{"description":"Story formats only: the director picks the story format that fits the idea best (storyFormat is the fallback). Default false.","type":"boolean"},"lengthSeconds":{"description":"How long it runs, in seconds: a story format 65, 75 or 85; any other format 30, 38, 46, 54, 60 or 65. Default: the format's own (75 or 46). Over 32 seconds needs Pro or higher.","type":"integer","minimum":20,"maximum":90},"language":{"description":"The language the characters speak (autoclips_options product fruit, option language). Default en.","type":"string","minLength":2,"maxLength":16},"aspectRatio":{"description":"Shape: The video's shape. A series keeps the shape of its Part 1.\nChoices:\n- 9:16 — 9:16: Vertical (TikTok/Reels).\n- 16:9 — 16:9: Horizontal (YouTube).\n- 1:1 — 1:1: Square.\nDefault: 9:16.","type":"string","enum":["9:16","16:9","1:1"]},"chemistry":{"description":"Chemistry: How much romance the couples show. Clothes stay on at every level.\nChoices:\n- clean — Clean: Barely touch. The story is the same.\n- flirty — Flirty: Hugs, an arm round a waist, looks that hold.\n- spicy — Spicy: Kissing and dancing too. Adds a dance track.\nDefault: flirty.","type":"string","enum":["clean","flirty","spicy"]},"look":{"description":"Look: How the cast is dressed. Left out, the format decides (Hot on glow-up, giant-curse and impossible-commission; Classic elsewhere), and an idea about a child or a teenager is always Classic by default. Hot is grown-ups (21+) only and never nudity. A series keeps its look unless a part picks one.\nChoices:\n- classic — Classic: Everyone dressed for the story.\n- hot — Hot: Glamorous grown-up leads: figure-hugging outfits, curves, cleavage. Never nudity.\nDefault: The format's own look (leave it out).","type":"string","enum":["classic","hot"]},"scriptModel":{"description":"Writer: Which AI writes the script. The writer sets the script's price.\nChoices:\n- opus — Claude Opus 5.5: Claude Opus 5.5 writes the script. (300 credits for the script)\n- gemini — Gemini 3.8 Flash: Gemini 3.8 Flash writes the script. (120 credits for the script)\n- muse — Muse Spark 1.3: Muse Spark 1.3 writes the script. (120 credits for the script)\n- kimi — Kimi K3: Kimi K3 writes the script. (200 credits for the script)\n- grok — Grok 4.6: Grok 4.6 writes the script. (110 credits for the script)\nDefault: opus.","type":"string","enum":["opus","gemini","muse","kimi","grok"]},"imageModel":{"description":"Picture model: Which model draws the character looks and the scene frames. It sets each picture's price.\nChoices:\n- nano-banana-2 — Nano Banana 2: Highest quality, best character consistency. (72 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2-high — Precision Max: Sharpest detail and the most literal prompt accuracy. (107 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2 — Precision: Same accuracy at a lower resolution — cheaper per image. (33 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-2-pro — FLUX 2 Pro: Excellent style adherence and detail. (48 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- nano-banana — Nano Banana: Good quality, faster generation. (24 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-kontext-pro — FLUX Kontext Pro: Good balance of quality and speed. (24 credits a picture)\n- flux-kontext-dev — FLUX Kontext Dev: Budget option for testing. (15 credits a picture)\n- krea-2-medium — Krea 2: Stunning aesthetics — style-reference consistency. (25 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\nDefault: nano-banana-2.","type":"string","enum":["nano-banana-2","gpt-image-2-high","gpt-image-2","flux-2-pro","nano-banana","flux-kontext-pro","flux-kontext-dev","krea-2-medium"]},"videoModel":{"description":"Video model: Which model films each scene's talking clip. The four AutoClips models and Reel are on the create page. AutoClips 1 Lite and Lite Full HD speak the lines in each character's voice (set it with the cast's voice option; voices are free). A Short Film is filmed on Cinematic Pro; the others are kept for older stories.\nChoices:\n- autoclips1 — AutoClips 1: Our main model. Strong acting, speaks every line. (12 credits a second of clip)\n- autoclips1Upscaled — AutoClips 1 1080p Upscaled: AutoClips 1, sharpened to 1080p. (16 credits a second of clip)\n- autoclips1Light — AutoClips 1 Lite: Half the price. Lines are spoken in the voices you pick. (6 credits a second of clip)\n- autoclips1LightHd — AutoClips 1 Lite Full HD: AutoClips 1 Lite drawn at full 1080p. (18 credits a second of clip)\n- autoclips — AutoClips 1 1080p Upscaled: The older name for AutoClips 1 1080p Upscaled, kept for saved stories and automations. (16 credits a second of clip)\n- minimax — Reel: Big expressive acting, one clean shot per scene, 10-second clips. (52 credits a second of clip)\n- omniMax — Pro Max: Best quality, fastest generation. (1500 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\n- veo31lite — Lite: Fast and affordable — 720p with audio. (240 credits a clip)\n- klingStd — Cinematic: Multi-shot — several camera angles cut together in one take. (600 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\n- klingPro — Cinematic Pro: Multi-shot at the highest quality tier. (810 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\nDefault: autoclips1.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd","autoclips","minimax","omniMax","veo31lite","klingStd","klingPro"]},"captions":{"description":"Burned-in word-by-word captions. Default true (a silent Short Film has none).","type":"boolean"},"music":{"title":"Background music (Fruit AI Stories and Animal Stories option music)","description":"Background music: The music bed, as \"<shelf>:<track id>\" (fai, popular or v3) or \"none\". Left out: story formats start on a copyright-free sad bed; other formats start with no music.\nOne of 333 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=fruit&option=music) to see them all.\nChoices:\n- none — No music: The story plays with its voices and sound only.\n- fai:fai-batida-funk — Batida Funk: Fruit picks shelf.\n- fai:fai-popular — Popular: Fruit picks shelf.\n- fai:fai-slowed — Slowed: Fruit picks shelf.\n- fai:fai-normal — Normal: Fruit picks shelf.\n- popular:hide-and-sneak — Hide and Sneak: Popular shelf.\n- popular:old-time-circus — Old Time Circus: Popular shelf.\n- popular:lurking-behind — Lurking Behind: Popular shelf.\n- popular:ce-burning-memory — It's Just a Burning Memory: Popular shelf.\n- popular:ce-f-down — F.Down: Popular shelf.\n- popular:ce-school-rooftop — School Rooftop (Bird Sounds): Popular shelf.\n- popular:ce-promise-reprise — Promise (Reprise): Popular shelf.\n- popular:ce-everything-in-its-right-place — Everything In Its Right Place (Instrumental): Popular shelf.\n- popular:ce-six-forty-seven — Six Forty Seven: Popular shelf.\n- popular:ce-numbers — Numbers (Instrumental): Popular shelf.\n- popular:ce-fallen-down — Fallen Down (Panic Room): Popular shelf.\n- popular:ce-char-remix — Char (Remix) Slowed: Popular shelf.\n- popular:ce-empathy — Empathy (Slowed + Reverb): Popular shelf.\n- popular:ce-aleph — ALEPH (Slowed + Reverb): Popular shelf.\n- popular:ce-solitude — Solitude (Slowed): Popular shelf.\n- popular:ce-closed-slowed — Closed (Slowed + Reverb): Popular shelf.\n- popular:ce-silhouette — Silhouette (Slowed Best Part): Popular shelf.\n- popular:ce-country-roads — Take Me Home, Country Roads (Karaoke): Popular shelf.\n- popular:ce-house-rising-sun — The House Of The Rising Sun (Instrumental): Popular shelf.\n- popular:ce-feeling-blue — Feeling Blue: Popular shelf.\n- popular:ce-stargazing — Stargazing (Sped Up): Popular shelf.\n- v3:animals-wildlife-01-wild-kingdom-v1 — Wild Kingdom: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-01-wild-kingdom-v2 — Wild Kingdom: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-02-migration-path-v1 — Migration Path: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-02-migration-path-v2 — Migration Path: Copyright-free shelf, copyright-free.\n…and 303 more.\nDefault: The format's default bed (leave it out).","type":"string"},"narrationMode":{"description":"Spoken or silent (Short Film): Short Film only: spoken (dense dialogue) or silent (no dialogue at all, the story told in pictures). Every other format is spoken. A series keeps it.\nChoices:\n- spoken — Spoken: The characters talk.\n- silent — Silent: Nobody speaks; no captions.\nDefault: spoken.","type":"string","enum":["spoken","silent"]},"videoSpeed":{"description":"Speed: How fast the finished video plays, 1x to 2x in steps of 0.1. Changing it on a finished video needs a new render. Series parts keep the speed of the series unless a part picks one. From 1 to 2 x, in steps of 0.1. Default: 1.","type":"number","minimum":1,"maximum":2,"multipleOf":0.1},"partLabel":{"description":"Story formats: show the \"PART N\" label. Default true.","type":"boolean"},"characterIds":{"description":"Fruit AI only: up to 8 characters from your library (yours, a preset or a public one) to cast. Left out: the writer invents the whole cast.","maxItems":8,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$"}}},"additionalProperties":false},"example":{"idea":"A shy cleaner is laughed at by the whole office; at midnight her forehead number changes.","storyFormat":"glow-up"}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"settings":{"description":"Every setting the story is made with, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"creditsNow":{"description":"What create charges (the script).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"creditsAbout":{"description":"About what the whole story comes to (looks, frames and clips are charged as they are made).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"creditsAtMost":{"description":"The most fruit_story make can spend on it (its default spending limit).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"breakdown":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["label","credits"],"additionalProperties":false}},"balance":{"type":"number"}},"required":["settings","creditsNow","creditsAbout","creditsAtMost","breakdown","balance"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"settings":{"species":"fruit","storyFormat":"glow-up","lengthSeconds":75},"creditsNow":300,"creditsAbout":2400,"creditsAtMost":4300,"breakdown":[{"label":"Script (charged at create)","credits":300}],"balance":12000}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/series":{"get":{"operationId":"fruit_series_list","summary":"List your Fruit and Animal series.","description":"List your Fruit and Animal series.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"fruit.series.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_series action=list","parameters":[{"name":"includeArchived","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"series":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"premise":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["active","archived"]},"species":{"type":"string","enum":["fruit","animal"]},"storyFormat":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"aspectRatio":{"anyOf":[{"type":"string"},{"type":"null"}]},"look":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextPartNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["characterId","name","kind","role"],"additionalProperties":false}},"parts":{"type":"array","items":{"type":"object","properties":{"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["partNumber","projectId","title","status","videoUrl"],"additionalProperties":false}},"synopsis":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCliffhanger":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","premise","status","species","storyFormat","language","aspectRatio","look","nextPartNumber","cast","parts","synopsis","lastCliffhanger","createdAt","updatedAt"],"additionalProperties":false}}},"required":["series"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"series":[{"id":"ser_6a1b2c3d","title":"The $5 Boy","premise":"A boy with $5 on his forehead at a school of millionaires.","status":"active","species":"fruit","storyFormat":"forehead-number","language":"en","aspectRatio":"9:16","look":null,"nextPartNumber":2,"cast":[{"characterId":"66f0a1b2c3d4e5f601234567","name":"Mango","kind":"mango","role":"lead"}],"parts":[{"partNumber":1,"projectId":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","status":"completed","videoUrl":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4"}],"synopsis":null,"lastCliffhanger":"His number starts to change.","createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:00:00.000Z"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/series/{seriesId}":{"get":{"operationId":"fruit_series_get","summary":"One series: its parts, cast and where the story is.","description":"One series: its parts, cast and where the story is.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"fruit.series.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_series action=get","parameters":[{"name":"seriesId","in":"path","required":true,"schema":{"description":"The series id (fruit_series list).","type":"string","minLength":1,"maxLength":80},"description":"The series id (fruit_series list).","example":"ser_6a1b2c3d"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"series":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"premise":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["active","archived"]},"species":{"type":"string","enum":["fruit","animal"]},"storyFormat":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"aspectRatio":{"anyOf":[{"type":"string"},{"type":"null"}]},"look":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextPartNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["characterId","name","kind","role"],"additionalProperties":false}},"parts":{"type":"array","items":{"type":"object","properties":{"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["partNumber","projectId","title","status","videoUrl"],"additionalProperties":false}},"synopsis":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCliffhanger":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","premise","status","species","storyFormat","language","aspectRatio","look","nextPartNumber","cast","parts","synopsis","lastCliffhanger","createdAt","updatedAt"],"additionalProperties":false}},"required":["series"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"series":{"id":"ser_6a1b2c3d","title":"The $5 Boy","premise":"A boy with $5 on his forehead at a school of millionaires.","status":"active","species":"fruit","storyFormat":"forehead-number","language":"en","aspectRatio":"9:16","look":null,"nextPartNumber":2,"cast":[{"characterId":"66f0a1b2c3d4e5f601234567","name":"Mango","kind":"mango","role":"lead"}],"parts":[{"partNumber":1,"projectId":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","status":"completed","videoUrl":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4"}],"synopsis":null,"lastCliffhanger":"His number starts to change.","createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:00:00.000Z"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"fruit_series_update","summary":"Rename a series, archive it or bring it back (free).","description":"Rename a series, archive it or bring it back (free).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"fruit.series.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"fruit_series action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":60},"status":{"type":"string","enum":["active","archived"]}},"additionalProperties":false},"example":{"status":"archived"}}}},"parameters":[{"name":"seriesId","in":"path","required":true,"schema":{"description":"The series id (fruit_series list).","type":"string","minLength":1,"maxLength":80},"description":"The series id (fruit_series list).","example":"ser_6a1b2c3d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"series":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"premise":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["active","archived"]},"species":{"type":"string","enum":["fruit","animal"]},"storyFormat":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"aspectRatio":{"anyOf":[{"type":"string"},{"type":"null"}]},"look":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextPartNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["characterId","name","kind","role"],"additionalProperties":false}},"parts":{"type":"array","items":{"type":"object","properties":{"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["partNumber","projectId","title","status","videoUrl"],"additionalProperties":false}},"synopsis":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCliffhanger":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","premise","status","species","storyFormat","language","aspectRatio","look","nextPartNumber","cast","parts","synopsis","lastCliffhanger","createdAt","updatedAt"],"additionalProperties":false}},"required":["series"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"series":{"id":"ser_6a1b2c3d","title":"The $5 Boy","premise":"A boy with $5 on his forehead at a school of millionaires.","status":"archived","species":"fruit","storyFormat":"forehead-number","language":"en","aspectRatio":"9:16","look":null,"nextPartNumber":2,"cast":[{"characterId":"66f0a1b2c3d4e5f601234567","name":"Mango","kind":"mango","role":"lead"}],"parts":[{"partNumber":1,"projectId":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","status":"completed","videoUrl":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4"}],"synopsis":null,"lastCliffhanger":"His number starts to change.","createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:00:00.000Z"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/series/{seriesId}/parts":{"post":{"operationId":"fruit_series_next_part","summary":"Start the next part of a series from the last part's cliffhanger, with the same cast. Charges the script.","description":"Starts Part N: it carries on from where the last part ended, with the same characters (same faces and voices), format, language and shape. Charges the script, as create does; then approve, continue and render it like any story (or use make_next_part). finale: true makes it the last part.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.series.next_part","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_series action=next_part","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idea":{"description":"Optional: steer this part (\"she finally confronts her sister\"). Left out: it carries on from the cliffhanger.","type":"string","maxLength":2000},"finale":{"description":"This part ends the story (a closing verdict instead of a cliffhanger). Default false.","type":"boolean"},"lengthSeconds":{"description":"How long it runs, in seconds: a story format 65, 75 or 85; any other format 30, 38, 46, 54, 60 or 65. Default: the format's own (75 or 46). Over 32 seconds needs Pro or higher.","type":"integer","minimum":20,"maximum":90},"chemistry":{"description":"Chemistry: How much romance the couples show. Clothes stay on at every level.\nChoices:\n- clean — Clean: Barely touch. The story is the same.\n- flirty — Flirty: Hugs, an arm round a waist, looks that hold.\n- spicy — Spicy: Kissing and dancing too. Adds a dance track.\nDefault: flirty.","type":"string","enum":["clean","flirty","spicy"]},"look":{"description":"Look: How the cast is dressed. Left out, the format decides (Hot on glow-up, giant-curse and impossible-commission; Classic elsewhere), and an idea about a child or a teenager is always Classic by default. Hot is grown-ups (21+) only and never nudity. A series keeps its look unless a part picks one.\nChoices:\n- classic — Classic: Everyone dressed for the story.\n- hot — Hot: Glamorous grown-up leads: figure-hugging outfits, curves, cleavage. Never nudity.\nDefault: The format's own look (leave it out).","type":"string","enum":["classic","hot"]},"scriptModel":{"description":"Writer: Which AI writes the script. The writer sets the script's price.\nChoices:\n- opus — Claude Opus 5.5: Claude Opus 5.5 writes the script. (300 credits for the script)\n- gemini — Gemini 3.8 Flash: Gemini 3.8 Flash writes the script. (120 credits for the script)\n- muse — Muse Spark 1.3: Muse Spark 1.3 writes the script. (120 credits for the script)\n- kimi — Kimi K3: Kimi K3 writes the script. (200 credits for the script)\n- grok — Grok 4.6: Grok 4.6 writes the script. (110 credits for the script)\nDefault: opus.","type":"string","enum":["opus","gemini","muse","kimi","grok"]},"imageModel":{"description":"Picture model: Which model draws the character looks and the scene frames. It sets each picture's price.\nChoices:\n- nano-banana-2 — Nano Banana 2: Highest quality, best character consistency. (72 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2-high — Precision Max: Sharpest detail and the most literal prompt accuracy. (107 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2 — Precision: Same accuracy at a lower resolution — cheaper per image. (33 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-2-pro — FLUX 2 Pro: Excellent style adherence and detail. (48 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- nano-banana — Nano Banana: Good quality, faster generation. (24 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-kontext-pro — FLUX Kontext Pro: Good balance of quality and speed. (24 credits a picture)\n- flux-kontext-dev — FLUX Kontext Dev: Budget option for testing. (15 credits a picture)\n- krea-2-medium — Krea 2: Stunning aesthetics — style-reference consistency. (25 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\nDefault: nano-banana-2.","type":"string","enum":["nano-banana-2","gpt-image-2-high","gpt-image-2","flux-2-pro","nano-banana","flux-kontext-pro","flux-kontext-dev","krea-2-medium"]},"videoModel":{"description":"Video model: Which model films each scene's talking clip. The four AutoClips models and Reel are on the create page. AutoClips 1 Lite and Lite Full HD speak the lines in each character's voice (set it with the cast's voice option; voices are free). A Short Film is filmed on Cinematic Pro; the others are kept for older stories.\nChoices:\n- autoclips1 — AutoClips 1: Our main model. Strong acting, speaks every line. (12 credits a second of clip)\n- autoclips1Upscaled — AutoClips 1 1080p Upscaled: AutoClips 1, sharpened to 1080p. (16 credits a second of clip)\n- autoclips1Light — AutoClips 1 Lite: Half the price. Lines are spoken in the voices you pick. (6 credits a second of clip)\n- autoclips1LightHd — AutoClips 1 Lite Full HD: AutoClips 1 Lite drawn at full 1080p. (18 credits a second of clip)\n- autoclips — AutoClips 1 1080p Upscaled: The older name for AutoClips 1 1080p Upscaled, kept for saved stories and automations. (16 credits a second of clip)\n- minimax — Reel: Big expressive acting, one clean shot per scene, 10-second clips. (52 credits a second of clip)\n- omniMax — Pro Max: Best quality, fastest generation. (1500 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\n- veo31lite — Lite: Fast and affordable — 720p with audio. (240 credits a clip)\n- klingStd — Cinematic: Multi-shot — several camera angles cut together in one take. (600 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\n- klingPro — Cinematic Pro: Multi-shot at the highest quality tier. (810 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\nDefault: autoclips1.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd","autoclips","minimax","omniMax","veo31lite","klingStd","klingPro"]},"captions":{"description":"Burned-in word-by-word captions. Default true (a silent Short Film has none).","type":"boolean"},"music":{"title":"Background music (Fruit AI Stories and Animal Stories option music)","description":"Background music: The music bed, as \"<shelf>:<track id>\" (fai, popular or v3) or \"none\". Left out: story formats start on a copyright-free sad bed; other formats start with no music.\nOne of 333 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=fruit&option=music) to see them all.\nChoices:\n- none — No music: The story plays with its voices and sound only.\n- fai:fai-batida-funk — Batida Funk: Fruit picks shelf.\n- fai:fai-popular — Popular: Fruit picks shelf.\n- fai:fai-slowed — Slowed: Fruit picks shelf.\n- fai:fai-normal — Normal: Fruit picks shelf.\n- popular:hide-and-sneak — Hide and Sneak: Popular shelf.\n- popular:old-time-circus — Old Time Circus: Popular shelf.\n- popular:lurking-behind — Lurking Behind: Popular shelf.\n- popular:ce-burning-memory — It's Just a Burning Memory: Popular shelf.\n- popular:ce-f-down — F.Down: Popular shelf.\n- popular:ce-school-rooftop — School Rooftop (Bird Sounds): Popular shelf.\n- popular:ce-promise-reprise — Promise (Reprise): Popular shelf.\n- popular:ce-everything-in-its-right-place — Everything In Its Right Place (Instrumental): Popular shelf.\n- popular:ce-six-forty-seven — Six Forty Seven: Popular shelf.\n- popular:ce-numbers — Numbers (Instrumental): Popular shelf.\n- popular:ce-fallen-down — Fallen Down (Panic Room): Popular shelf.\n- popular:ce-char-remix — Char (Remix) Slowed: Popular shelf.\n- popular:ce-empathy — Empathy (Slowed + Reverb): Popular shelf.\n- popular:ce-aleph — ALEPH (Slowed + Reverb): Popular shelf.\n- popular:ce-solitude — Solitude (Slowed): Popular shelf.\n- popular:ce-closed-slowed — Closed (Slowed + Reverb): Popular shelf.\n- popular:ce-silhouette — Silhouette (Slowed Best Part): Popular shelf.\n- popular:ce-country-roads — Take Me Home, Country Roads (Karaoke): Popular shelf.\n- popular:ce-house-rising-sun — The House Of The Rising Sun (Instrumental): Popular shelf.\n- popular:ce-feeling-blue — Feeling Blue: Popular shelf.\n- popular:ce-stargazing — Stargazing (Sped Up): Popular shelf.\n- v3:animals-wildlife-01-wild-kingdom-v1 — Wild Kingdom: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-01-wild-kingdom-v2 — Wild Kingdom: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-02-migration-path-v1 — Migration Path: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-02-migration-path-v2 — Migration Path: Copyright-free shelf, copyright-free.\n…and 303 more.\nDefault: The format's default bed (leave it out).","type":"string"},"videoSpeed":{"description":"Speed: How fast the finished video plays, 1x to 2x in steps of 0.1. Changing it on a finished video needs a new render. Series parts keep the speed of the series unless a part picks one. From 1 to 2 x, in steps of 0.1. Default: 1.","type":"number","minimum":1,"maximum":2,"multipleOf":0.1},"partLabel":{"description":"Story formats: show the \"PART N\" label. Default true.","type":"boolean"},"characterIds":{"description":"Fruit AI only: up to 8 characters from your library (yours, a preset or a public one) to cast. Left out: the writer invents the whole cast.","maxItems":8,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$"}},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"seriesId","in":"path","required":true,"schema":{"description":"The series id (fruit_series list).","type":"string","minLength":1,"maxLength":80},"description":"The series id (fruit_series list).","example":"ser_6a1b2c3d"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"partNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"creditsCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","job","partNumber","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"drafting","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":{"seriesId":"ser_6a1b2c3d","title":"The $5 Boy","partNumber":2,"finale":false},"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"job":{"id":"job_019a1b2c3d4e5f60718293cd","product":"fruit","kind":"fruit.story","resource":{"type":"fruit_project","id":"5f1e2d3c-4b5a-4968-8776-655443322110"},"status":"queued","step":"Writing the next part","progress":null,"result":null,"error":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T09:00:00.000Z","finishedAt":null,"poll_after_seconds":30},"partNumber":2,"creditsCharged":300}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fruit/series/{seriesId}/parts/make":{"post":{"operationId":"fruit_series_make_next_part","summary":"Make the next part of a series in one go, within a spending limit. Answers with a job.","description":"Like next_part, then the autopilot approves, films and renders it (fruit_story make). What you approve is a spending limit (limitCredits; left out, the most this part can cost), and it is the most the run can be charged; the part stops before a step that would pass it.\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. The limit is the most Fruit story can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Fruit AI Stories and Animal Stories"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"fruit.series.make_next_part","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"fruit_series action=make_next_part","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idea":{"description":"Optional: steer this part (\"she finally confronts her sister\"). Left out: it carries on from the cliffhanger.","type":"string","maxLength":2000},"finale":{"description":"This part ends the story (a closing verdict instead of a cliffhanger). Default false.","type":"boolean"},"lengthSeconds":{"description":"How long it runs, in seconds: a story format 65, 75 or 85; any other format 30, 38, 46, 54, 60 or 65. Default: the format's own (75 or 46). Over 32 seconds needs Pro or higher.","type":"integer","minimum":20,"maximum":90},"chemistry":{"description":"Chemistry: How much romance the couples show. Clothes stay on at every level.\nChoices:\n- clean — Clean: Barely touch. The story is the same.\n- flirty — Flirty: Hugs, an arm round a waist, looks that hold.\n- spicy — Spicy: Kissing and dancing too. Adds a dance track.\nDefault: flirty.","type":"string","enum":["clean","flirty","spicy"]},"look":{"description":"Look: How the cast is dressed. Left out, the format decides (Hot on glow-up, giant-curse and impossible-commission; Classic elsewhere), and an idea about a child or a teenager is always Classic by default. Hot is grown-ups (21+) only and never nudity. A series keeps its look unless a part picks one.\nChoices:\n- classic — Classic: Everyone dressed for the story.\n- hot — Hot: Glamorous grown-up leads: figure-hugging outfits, curves, cleavage. Never nudity.\nDefault: The format's own look (leave it out).","type":"string","enum":["classic","hot"]},"scriptModel":{"description":"Writer: Which AI writes the script. The writer sets the script's price.\nChoices:\n- opus — Claude Opus 5.5: Claude Opus 5.5 writes the script. (300 credits for the script)\n- gemini — Gemini 3.8 Flash: Gemini 3.8 Flash writes the script. (120 credits for the script)\n- muse — Muse Spark 1.3: Muse Spark 1.3 writes the script. (120 credits for the script)\n- kimi — Kimi K3: Kimi K3 writes the script. (200 credits for the script)\n- grok — Grok 4.6: Grok 4.6 writes the script. (110 credits for the script)\nDefault: opus.","type":"string","enum":["opus","gemini","muse","kimi","grok"]},"imageModel":{"description":"Picture model: Which model draws the character looks and the scene frames. It sets each picture's price.\nChoices:\n- nano-banana-2 — Nano Banana 2: Highest quality, best character consistency. (72 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2-high — Precision Max: Sharpest detail and the most literal prompt accuracy. (107 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- gpt-image-2 — Precision: Same accuracy at a lower resolution — cheaper per image. (33 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-2-pro — FLUX 2 Pro: Excellent style adherence and detail. (48 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- nano-banana — Nano Banana: Good quality, faster generation. (24 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\n- flux-kontext-pro — FLUX Kontext Pro: Good balance of quality and speed. (24 credits a picture)\n- flux-kontext-dev — FLUX Kontext Dev: Budget option for testing. (15 credits a picture)\n- krea-2-medium — Krea 2: Stunning aesthetics — style-reference consistency. (25 credits a picture; plans: pro, advanced, enterprise, ultra, legacy)\nDefault: nano-banana-2.","type":"string","enum":["nano-banana-2","gpt-image-2-high","gpt-image-2","flux-2-pro","nano-banana","flux-kontext-pro","flux-kontext-dev","krea-2-medium"]},"videoModel":{"description":"Video model: Which model films each scene's talking clip. The four AutoClips models and Reel are on the create page. AutoClips 1 Lite and Lite Full HD speak the lines in each character's voice (set it with the cast's voice option; voices are free). A Short Film is filmed on Cinematic Pro; the others are kept for older stories.\nChoices:\n- autoclips1 — AutoClips 1: Our main model. Strong acting, speaks every line. (12 credits a second of clip)\n- autoclips1Upscaled — AutoClips 1 1080p Upscaled: AutoClips 1, sharpened to 1080p. (16 credits a second of clip)\n- autoclips1Light — AutoClips 1 Lite: Half the price. Lines are spoken in the voices you pick. (6 credits a second of clip)\n- autoclips1LightHd — AutoClips 1 Lite Full HD: AutoClips 1 Lite drawn at full 1080p. (18 credits a second of clip)\n- autoclips — AutoClips 1 1080p Upscaled: The older name for AutoClips 1 1080p Upscaled, kept for saved stories and automations. (16 credits a second of clip)\n- minimax — Reel: Big expressive acting, one clean shot per scene, 10-second clips. (52 credits a second of clip)\n- omniMax — Pro Max: Best quality, fastest generation. (1500 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\n- veo31lite — Lite: Fast and affordable — 720p with audio. (240 credits a clip)\n- klingStd — Cinematic: Multi-shot — several camera angles cut together in one take. (600 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\n- klingPro — Cinematic Pro: Multi-shot at the highest quality tier. (810 credits a clip; plans: pro, advanced, enterprise, ultra, legacy)\nDefault: autoclips1.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd","autoclips","minimax","omniMax","veo31lite","klingStd","klingPro"]},"captions":{"description":"Burned-in word-by-word captions. Default true (a silent Short Film has none).","type":"boolean"},"music":{"title":"Background music (Fruit AI Stories and Animal Stories option music)","description":"Background music: The music bed, as \"<shelf>:<track id>\" (fai, popular or v3) or \"none\". Left out: story formats start on a copyright-free sad bed; other formats start with no music.\nOne of 333 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=fruit&option=music) to see them all.\nChoices:\n- none — No music: The story plays with its voices and sound only.\n- fai:fai-batida-funk — Batida Funk: Fruit picks shelf.\n- fai:fai-popular — Popular: Fruit picks shelf.\n- fai:fai-slowed — Slowed: Fruit picks shelf.\n- fai:fai-normal — Normal: Fruit picks shelf.\n- popular:hide-and-sneak — Hide and Sneak: Popular shelf.\n- popular:old-time-circus — Old Time Circus: Popular shelf.\n- popular:lurking-behind — Lurking Behind: Popular shelf.\n- popular:ce-burning-memory — It's Just a Burning Memory: Popular shelf.\n- popular:ce-f-down — F.Down: Popular shelf.\n- popular:ce-school-rooftop — School Rooftop (Bird Sounds): Popular shelf.\n- popular:ce-promise-reprise — Promise (Reprise): Popular shelf.\n- popular:ce-everything-in-its-right-place — Everything In Its Right Place (Instrumental): Popular shelf.\n- popular:ce-six-forty-seven — Six Forty Seven: Popular shelf.\n- popular:ce-numbers — Numbers (Instrumental): Popular shelf.\n- popular:ce-fallen-down — Fallen Down (Panic Room): Popular shelf.\n- popular:ce-char-remix — Char (Remix) Slowed: Popular shelf.\n- popular:ce-empathy — Empathy (Slowed + Reverb): Popular shelf.\n- popular:ce-aleph — ALEPH (Slowed + Reverb): Popular shelf.\n- popular:ce-solitude — Solitude (Slowed): Popular shelf.\n- popular:ce-closed-slowed — Closed (Slowed + Reverb): Popular shelf.\n- popular:ce-silhouette — Silhouette (Slowed Best Part): Popular shelf.\n- popular:ce-country-roads — Take Me Home, Country Roads (Karaoke): Popular shelf.\n- popular:ce-house-rising-sun — The House Of The Rising Sun (Instrumental): Popular shelf.\n- popular:ce-feeling-blue — Feeling Blue: Popular shelf.\n- popular:ce-stargazing — Stargazing (Sped Up): Popular shelf.\n- v3:animals-wildlife-01-wild-kingdom-v1 — Wild Kingdom: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-01-wild-kingdom-v2 — Wild Kingdom: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-02-migration-path-v1 — Migration Path: Copyright-free shelf, copyright-free.\n- v3:animals-wildlife-02-migration-path-v2 — Migration Path: Copyright-free shelf, copyright-free.\n…and 303 more.\nDefault: The format's default bed (leave it out).","type":"string"},"videoSpeed":{"description":"Speed: How fast the finished video plays, 1x to 2x in steps of 0.1. Changing it on a finished video needs a new render. Series parts keep the speed of the series unless a part picks one. From 1 to 2 x, in steps of 0.1. Default: 1.","type":"number","minimum":1,"maximum":2,"multipleOf":0.1},"partLabel":{"description":"Story formats: show the \"PART N\" label. Default true.","type":"boolean"},"characterIds":{"description":"Fruit AI only: up to 8 characters from your library (yours, a preset or a public one) to cast. Left out: the writer invents the whole cast.","maxItems":8,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$"}},"limitCredits":{"type":"integer","minimum":1,"maximum":100000},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"additionalProperties":false},"example":{"limitCredits":3000}}}},"parameters":[{"name":"seriesId","in":"path","required":true,"schema":{"description":"The series id (fruit_series list).","type":"string","minLength":1,"maxLength":80},"description":"The series id (fruit_series list).","example":"ser_6a1b2c3d"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"stage":{"description":"Where the story is: drafting, choosing_script, casting, cast_ready, drawing_frames, frames_ready, filming, editing, ready_to_render, rendering, completed or failed.","type":"string","enum":["drafting","choosing_script","casting","cast_ready","drawing_frames","frames_ready","filming","editing","ready_to_render","rendering","completed","failed"]},"status":{"type":"string"},"nextAction":{"description":"What waits for you: select_script (fruit_story), make_looks (fruit_cast), approve and continue (fruit_story), render (fruit_finish), retry (fruit_projects). null while it works or when it is done.","anyOf":[{"type":"string","enum":["select_script","make_looks","approve","continue","render","retry"]},{"type":"null"}]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentStep":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false},{"type":"null"}]},"demo":{"type":"boolean"},"settings":{"description":"Every setting the story is made with.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"scriptOptions":{"type":"array","items":{"type":"object","properties":{"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["variantId","title","logline"],"additionalProperties":false}},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"sceneNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"type":"array","items":{"type":"string"}},"dialogue":{"type":"array","items":{"type":"object","properties":{"character":{"anyOf":[{"type":"string"},{"type":"null"}]},"line":{"anyOf":[{"type":"string"},{"type":"null"}]},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["character","line","emotion"],"additionalProperties":false}},"frame":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeVersion":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","status","versions","activeVersion"],"additionalProperties":false},{"type":"null"}]},"clip":{"anyOf":[{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeCandidate":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","candidates","activeCandidate"],"additionalProperties":false},{"type":"null"}]},"clipStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sceneNumber","location","description","characters","dialogue","frame","clip","clipStatus"],"additionalProperties":false}}},"required":["title","logline","scenes"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"number"},{"type":"null"}]},"characterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"looks":{"type":"array","items":{"type":"object","properties":{"lookKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["lookKey","label","status","imageUrl"],"additionalProperties":false}}},"required":["castId","name","kind","role","gender","age","characterId","looks"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"slot":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slot","name","status","imageUrl"],"additionalProperties":false}},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"versions":{"type":"array","items":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","createdAt"],"additionalProperties":false}}},"required":["url","status","progress","versions"],"additionalProperties":false},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"number"},{"type":"null"}]},"finale":{"type":"boolean"}},"required":["seriesId","title","partNumber","finale"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags"],"additionalProperties":false},{"type":"null"}]},"autopilot":{"anyOf":[{"type":"object","properties":{"on":{"type":"boolean"},"limitCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["on","limitCredits","state","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"}},"required":["used"],"additionalProperties":false},"pricing":{"description":"What the next steps cost right now (the page's own figures).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","stage","status","nextAction","progress","currentStep","error","demo","settings","scriptOptions","script","cast","locations","video","series","post","autopilot","credits","pricing","createdAt","updatedAt","appUrl"],"additionalProperties":false},"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"partNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"limitCredits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","job","partNumber","limitCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"5f1e2d3c-4b5a-4968-8776-655443322110","title":"The $5 Boy","stage":"drafting","status":"completed","nextAction":null,"progress":100,"currentStep":"Video ready!","error":null,"demo":false,"settings":{"species":"fruit","storyFormat":"forehead-number","lengthSeconds":75,"language":"en","aspectRatio":"9:16","look":"classic","videoSpeed":1},"scriptOptions":[],"script":{"title":"The $5 Boy","logline":"A boy with $5 on his forehead starts at a school of millionaires.","scenes":[]},"cast":[],"locations":[],"video":{"url":"https://media.autoclips.app/videos/v3-cinematic/example/fruit_story.mp4","status":"completed","progress":100,"versions":[]},"series":null,"post":{"title":"He had $5. They had millions.","description":"Part 1","hashtags":["#fruitai"]},"autopilot":null,"credits":{"used":2340},"pricing":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T10:10:00.000Z","appUrl":"https://app.autoclips.app/fruit-stories/5f1e2d3c-4b5a-4968-8776-655443322110"},"job":{"id":"job_019a1b2c3d4e5f60718293ce","product":"fruit","kind":"fruit.story","resource":{"type":"fruit_project","id":"5f1e2d3c-4b5a-4968-8776-655443322110"},"status":"queued","step":"Making the next part","progress":null,"result":null,"error":null,"createdAt":"2026-10-27T09:00:00.000Z","updatedAt":"2026-10-27T09:00:00.000Z","finishedAt":null,"poll_after_seconds":30},"partNumber":2,"limitCredits":3000}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs":{"get":{"operationId":"shared_jobs_list","summary":"List your jobs, newest first. Filter by status or product.","description":"Lists the jobs on your account, newest first, 20 at a time (up to 100). Use status \"active\" for jobs still queued or running. Jobs that are still going are re-checked against the project, up to 25 per page and within about 6 seconds in all. A job that was not re-checked shows its last known state and carries a note; get it by its id for the latest. When you filter by status, a page ends early rather than leave out a job whose status could not be confirmed; the next page starts with that job, shown with its note. So a filtered page can hold fewer items than the limit while has_more is true.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.jobs.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_jobs action=list","parameters":[{"name":"status","in":"query","required":false,"schema":{"description":"Only jobs with this status. \"active\" means queued or running.","type":"string","enum":["active","queued","running","succeeded","failed","canceled"]},"description":"Only jobs with this status. \"active\" means queued or running.","example":"active"},{"name":"product","in":"query","required":false,"schema":{"description":"Only jobs from this product: shared, v3, ce, studio, stickman or fruit.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"description":"Only jobs from this product: shared, v3, ce, studio, stickman or fruit.","example":"studio"},{"name":"limit","in":"query","required":false,"schema":{"description":"How many items to return (1–100, default 20).","type":"integer","minimum":1,"maximum":100},"description":"How many items to return (1–100, default 20).","example":10},{"name":"cursor","in":"query","required":false,"schema":{"description":"The next_cursor from the previous page.","type":"string","maxLength":512},"description":"The next_cursor from the previous page.","example":"eyJhZnRlciI6ImpvYl8wMWEwZTQxODY4ODA0ZjJlN2ExYjZjOWQifQ"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"has_more":{"type":"boolean"}},"required":["items","next_cursor","has_more"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"items":[{"id":"job_01a0e7735350c3b9d2a5e817","product":"v3","kind":"v3.render","resource":{"type":"project","id":"v3_8f14e45fceea167a"},"status":"running","step":"rendering","progress":45,"result":null,"error":null,"createdAt":"2026-09-28T09:58:10.000Z","updatedAt":"2026-09-28T10:01:02.000Z","finishedAt":null,"poll_after_seconds":10}],"next_cursor":null,"has_more":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{jobId}":{"get":{"operationId":"shared_jobs_get","summary":"Check on long work: its status, step, percent done and result.","description":"Returns one job: queued, running, succeeded, failed or canceled, plus the step it is on, the percent done, and what it made once it succeeded. The status is read from the project itself each time you ask. Wait poll_after_seconds before asking again; once the status is final the job no longer changes.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.jobs.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_jobs action=get","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"description":"The job id you got back from the call that started the work.","type":"string","pattern":"^job_[0-9a-f]{24}$"},"description":"The job id you got back from the call that started the work.","example":"job_01a0e7735350c3b9d2a5e817"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"id":"job_01a0e7735350c3b9d2a5e817","product":"v3","kind":"v3.render","resource":{"type":"project","id":"v3_8f14e45fceea167a"},"status":"running","step":"rendering","progress":45,"result":null,"error":null,"createdAt":"2026-09-28T09:58:10.000Z","updatedAt":"2026-09-28T10:01:02.000Z","finishedAt":null,"poll_after_seconds":10}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/keys":{"get":{"operationId":"shared_keys_list","summary":"List your API keys (never the secrets).","description":"List your API keys (never the secrets).\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.keys.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","parameters":[{"name":"includeRevoked","in":"query","required":false,"schema":{"description":"Also show revoked keys.","type":"boolean"},"description":"Also show revoked keys."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"last4":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["read","edit","spend","delete","publish"]}},"dailyCreditCap":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"revokedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","last4","scopes","dailyCreditCap","createdAt","lastUsedAt","revokedAt"],"additionalProperties":false}}},"required":["keys"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"keys":[{"id":"key_1a2b3c4d5e6f7a8b","name":"Zapier","last4":"9f3c","scopes":["read","edit"],"dailyCreditCap":500,"createdAt":"2026-09-28T10:00:00.000Z","lastUsedAt":null,"revokedAt":null}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"shared_keys_create","summary":"Create an API key. The secret is shown once.","description":"Pick a name, the permissions (scopes) and, if you like, a daily credit cap for this key. Scopes: read, edit, spend, delete, publish.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.keys.create","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"scopes":{"description":"Defaults to every scope.","minItems":1,"maxItems":5,"type":"array","items":{"type":"string","enum":["read","edit","spend","delete","publish"]}},"dailyCreditCap":{"description":"Most credits this key may spend per UTC day. Omit or null for no cap of its own (the account's daily limit for API keys and AI apps still applies).","anyOf":[{"type":"integer","minimum":1,"maximum":10000000},{"type":"null"}]}},"required":["name"],"additionalProperties":false},"example":{"name":"Dashboard","scopes":["read"]}}}},"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"key":{"description":"The secret key. Shown ONCE; store it now.","type":"string"},"record":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"last4":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["read","edit","spend","delete","publish"]}},"dailyCreditCap":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"revokedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","last4","scopes","dailyCreditCap","createdAt","lastUsedAt","revokedAt"],"additionalProperties":false}},"required":["key","record"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"key":"ac_live_…","record":{"id":"key_1a2b3c4d5e6f7a8b","name":"Dashboard","last4":"9f3c","scopes":["read"],"dailyCreditCap":null,"createdAt":"2026-09-28T10:00:00.000Z","lastUsedAt":null,"revokedAt":null}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/keys/{keyId}":{"patch":{"operationId":"shared_keys_update","summary":"Rename a key, change its scopes or its daily credit cap.","description":"Rename a key, change its scopes or its daily credit cap.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.keys.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"scopes":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","enum":["read","edit","spend","delete","publish"]}},"dailyCreditCap":{"anyOf":[{"type":"integer","minimum":1,"maximum":10000000},{"type":"null"}]}},"additionalProperties":false},"example":{"dailyCreditCap":1000}}}},"parameters":[{"name":"keyId","in":"path","required":true,"schema":{"description":"keyId","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"keyId","example":"key_1a2b3c4d5e6f7a8b"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"last4":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["read","edit","spend","delete","publish"]}},"dailyCreditCap":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"revokedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","last4","scopes","dailyCreditCap","createdAt","lastUsedAt","revokedAt"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"shared_keys_revoke","summary":"Revoke a key. It stops working immediately.","description":"Revoke a key. It stops working immediately.\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["Account, media and publishing"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"shared.keys.revoke","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"keyId","in":"path","required":true,"schema":{"description":"keyId","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"keyId","example":"key_1a2b3c4d5e6f7a8b"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"last4":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["read","edit","spend","delete","publish"]}},"dailyCreditCap":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"revokedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","last4","scopes","dailyCreditCap","createdAt","lastUsedAt","revokedAt"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/keys/{keyId}/rotate":{"post":{"operationId":"shared_keys_rotate","summary":"Replace a key with a new secret (same name, scopes and cap). The old one stops working.","description":"Replace a key with a new secret (same name, scopes and cap). The old one stops working.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.keys.rotate","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"keyId","in":"path","required":true,"schema":{"description":"keyId","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"keyId","example":"key_1a2b3c4d5e6f7a8b"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"key":{"description":"The secret key. Shown ONCE; store it now.","type":"string"},"record":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"last4":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["read","edit","spend","delete","publish"]}},"dailyCreditCap":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"revokedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","last4","scopes","dailyCreditCap","createdAt","lastUsedAt","revokedAt"],"additionalProperties":false}},"required":["key","record"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me":{"get":{"operationId":"shared_account_whoami","summary":"Who this key belongs to and what it is allowed to do.","description":"Returns the account the key belongs to, the kind of credential used, its permissions (scopes) and its daily credit cap, and the account's daily limit for API keys and AI apps with what counts against it today. notes says in words which limit holds. Call it first to check a key works.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.account.whoami","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_account action=whoami","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"userId":{"type":"string"},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"credential":{"type":"object","properties":{"type":{"type":"string","enum":["api_key","legacy_mcp_key","oauth","session"]},"id":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"dailyCreditCap":{"description":"This key's own daily cap, set when the key was made (API keys only; null when it has none). The account's daily limit holds as well: whichever is lower is the most this key can spend in a day. notes says which.","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["type","id","scopes","dailyCreditCap"],"additionalProperties":false},"account":{"type":"object","properties":{"plan":{"description":"The plan in plain words: \"free plan\", \"Pro plan (monthly)\", \"Pro lifetime plan\" (the same words as credits planName).","type":"string"},"dailyCreditLimit":{"description":"The most this account may spend in a UTC day through API keys and AI apps together. null when signed in on the website, which has no limit. Change it in Settings → API.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"spentToday":{"description":"Credits counted against that limit today (UTC).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["plan","dailyCreditLimit","spentToday"],"additionalProperties":false},"notes":{"description":"The daily limit, and how the key's own cap sits under it, in plain words.","type":"array","items":{"type":"string"}}},"required":["userId","email","credential","account","notes"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"userId":"5dc8655f-0000-4000-8000-000000000000","email":"you@example.com","credential":{"type":"api_key","id":"key_1a2b3c4d5e6f7a8b","scopes":["read","edit","spend","delete","publish"],"dailyCreditCap":null},"account":{"plan":"Pro plan (monthly)","dailyCreditLimit":6000,"spentToday":240},"notes":["Daily limit for API keys and AI apps together: 6,000 credits, 240 used today (it starts again at 00:00 UTC; change it in Settings → API)."]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/voice-model":{"get":{"operationId":"shared_account_voice_model_get","summary":"Your account's voice model: the one every new V3 and Character Explainer video starts on.","description":"Returns your account's voice model (the narration model your new videos start on, shared by V3 and Character Explainer, the same pick as in the app) and every model you can pick: eleven_v4 (Eleven v4), eleven_v3 (Eleven v3), eleven_multilingual_v2 (Multilingual v2). Change it with set_voice_model (PUT /me/voice-model).\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.account.voice_model.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_account action=voice_model","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"voiceModel":{"description":"The account's voice model id.","type":"string","enum":["eleven_v4","eleven_v3","eleven_multilingual_v2"]},"label":{"description":"Its name in the app.","type":"string"},"usedFor":{"description":"What it applies to.","type":"string"},"choices":{"description":"Every voice model you can pick.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["id","label","description"],"additionalProperties":false}}},"required":["voiceModel","label","usedFor","choices"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"voiceModel":"eleven_v4","label":"Eleven v4","usedFor":"Every new V3 and Character Explainer video starts on it, in the app and through the API, unless a voice model is named for that video. A video keeps the model it was made with.","choices":[{"id":"eleven_v4","label":"Eleven v4","description":"Eleven v4."},{"id":"eleven_v3","label":"Eleven v3","description":"Eleven v3."},{"id":"eleven_multilingual_v2","label":"Multilingual v2","description":"Multilingual v2."}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"shared_account_voice_model_set","summary":"Change your account's voice model, the one every new V3 and Character Explainer video starts on. Free.","description":"Saves the voice model your new V3 and Character Explainer videos start on, exactly as picking it in the app does (the app shows the same pick). Videos already made keep their own model; a video can still name another one. Free. One of: eleven_v4 (Eleven v4), eleven_v3 (Eleven v3), eleven_multilingual_v2 (Multilingual v2).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.account.voice_model.set","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_account action=set_voice_model","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"voiceModel":{"description":"The voice model: eleven_v4 (Eleven v4), eleven_v3 (Eleven v3), eleven_multilingual_v2 (Multilingual v2).","type":"string","enum":["eleven_v4","eleven_v3","eleven_multilingual_v2"]}},"required":["voiceModel"],"additionalProperties":false},"example":{"voiceModel":"eleven_multilingual_v2"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"voiceModel":{"description":"The account's voice model id.","type":"string","enum":["eleven_v4","eleven_v3","eleven_multilingual_v2"]},"label":{"description":"Its name in the app.","type":"string"},"usedFor":{"description":"What it applies to.","type":"string"},"choices":{"description":"Every voice model you can pick.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["id","label","description"],"additionalProperties":false}}},"required":["voiceModel","label","usedFor","choices"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/media":{"get":{"operationId":"shared_media_list","summary":"List the pictures, videos and sounds in your library, newest first.","description":"Everything listed can be used in an AutoClips video. Filter by type (image, video, audio), by the project it was uploaded for, or by where it came from (upload or ai). Pages of up to 100; send next_cursor as cursor for the next page.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.media.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_media action=list","parameters":[{"name":"type","in":"query","required":false,"schema":{"description":"Only this kind: image, video or audio. Default: all three.","type":"string","enum":["image","video","audio"]},"description":"Only this kind: image, video or audio. Default: all three.","example":"image"},{"name":"projectId","in":"query","required":false,"schema":{"description":"Optional. The project these files are for. Later, list with this projectId to find them.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"example":"proj_bakery"},{"name":"source","in":"query","required":false,"schema":{"description":"upload = files people uploaded, ai = files AutoClips generated, library = finished videos brought in for the Video Editor, all (default).","type":"string","enum":["upload","ai","library","all"]},"description":"upload = files people uploaded, ai = files AutoClips generated, library = finished videos brought in for the Video Editor, all (default).","example":"upload"},{"name":"limit","in":"query","required":false,"schema":{"description":"How many items to return (1–100, default 20).","type":"integer","minimum":1,"maximum":100},"description":"How many items to return (1–100, default 20).","example":20},{"name":"cursor","in":"query","required":false,"schema":{"description":"The next_cursor from the previous page.","type":"string","maxLength":512},"description":"The next_cursor from the previous page."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"has_more":{"type":"boolean"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The media id. Other tools take it as mediaId.","type":"string"},"type":{"description":"image, video or audio.","type":"string","enum":["image","video","audio"]},"mimeType":{"description":"The real file type, detected from the file itself.","anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"size":{"description":"Size in bytes.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"url":{"description":"Where the file is stored. Works in AutoClips projects.","type":"string"},"projectId":{"description":"The project it was uploaded for, if any.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"upload = someone uploaded it; ai = AutoClips generated it; library = one of your finished AutoClips videos, brought in for the Video Editor (autoclips_editor import_video).","type":"string","enum":["upload","ai","library"]}},"required":["id","type","mimeType","name","size","url","projectId","createdAt","source"],"additionalProperties":false}}},"required":["next_cursor","has_more","items"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"items":[{"id":"66f7c0ffee00000000000002","type":"audio","mimeType":"audio/mpeg","name":"voice-note.mp3","size":1203311,"url":"https://media.autoclips.app/clips/character-explainer/5dc8655f-0000-4000-8000-000000000000/api/7d1e2c3b-1a2b-4c3d-8e9f-0a1b2c3d4e5f.mp3","projectId":"proj_bakery","createdAt":"2026-09-28T10:00:00.000Z","source":"upload"},{"id":"66f7c0ffee00000000000001","type":"image","mimeType":"image/png","name":"bakery-front.png","size":482113,"url":"https://media.autoclips.app/clips/character-explainer/5dc8655f-0000-4000-8000-000000000000/api/0b6f3a52-6f7e-4d9c-9d0e-3f4f0b1c2d3e.png","projectId":"proj_bakery","createdAt":"2026-09-28T10:00:00.000Z","source":"upload"}],"next_cursor":null,"has_more":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"shared_media_upload","summary":"Upload 1 to 10 files (multipart/form-data, field \"file\") into your library.","description":"Send a multipart/form-data body with 1 to 10 files in fields called \"file\" (and optionally a projectId field, or ?projectId= in the address). JPG, PNG, WebP or GIF pictures; MP4, MOV or WebM videos; MP3, WAV, M4A, AAC or OGG sounds. Pictures up to 25 MB, videos up to 95 MB, sounds up to 50 MB. All files together up to 95 MB. For a bigger video (up to 100 MB), put it on a public link and use import. The type is read from the file itself, not its name. Some phone videos (HEVC, the iPhone default) may need converting to a standard MP4 before they play everywhere. If any file is refused, none are stored. An Idempotency-Key is optional here: with one, a retry returns the first result, but the key is matched on the address only, not the file bytes, so use a fresh key for every new upload.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.media.upload","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"array","items":{"type":"string","format":"binary"},"minItems":1,"maxItems":10,"description":"One or more files in fields named \"file\" (up to 10)."}},"required":["file"]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."},{"name":"projectId","in":"query","required":false,"schema":{"description":"Optional. The project these files are for. Later, list with this projectId to find them.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"example":"proj_bakery"}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The media id. Other tools take it as mediaId.","type":"string"},"type":{"description":"image, video or audio.","type":"string","enum":["image","video","audio"]},"mimeType":{"description":"The real file type, detected from the file itself.","anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"size":{"description":"Size in bytes.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"url":{"description":"Where the file is stored. Works in AutoClips projects.","type":"string"},"projectId":{"description":"The project it was uploaded for, if any.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"upload = someone uploaded it; ai = AutoClips generated it; library = one of your finished AutoClips videos, brought in for the Video Editor (autoclips_editor import_video).","type":"string","enum":["upload","ai","library"]}},"required":["id","type","mimeType","name","size","url","projectId","createdAt","source"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"items":[{"id":"66f7c0ffee00000000000001","type":"image","mimeType":"image/png","name":"bakery-front.png","size":482113,"url":"https://media.autoclips.app/clips/character-explainer/5dc8655f-0000-4000-8000-000000000000/api/0b6f3a52-6f7e-4d9c-9d0e-3f4f0b1c2d3e.png","projectId":"proj_bakery","createdAt":"2026-09-28T10:00:00.000Z","source":"upload"},{"id":"66f7c0ffee00000000000002","type":"audio","mimeType":"audio/mpeg","name":"voice-note.mp3","size":1203311,"url":"https://media.autoclips.app/clips/character-explainer/5dc8655f-0000-4000-8000-000000000000/api/7d1e2c3b-1a2b-4c3d-8e9f-0a1b2c3d4e5f.mp3","projectId":"proj_bakery","createdAt":"2026-09-28T10:00:00.000Z","source":"upload"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/media/import":{"post":{"operationId":"shared_media_import","summary":"Copy a file from a public https link (Google Drive, Dropbox or any direct link) into your library.","description":"The link must open without signing in (Google Drive: shared with \"Anyone with the link\"). Drive and Dropbox share links are turned into download links for you. Only public internet addresses are fetched. JPG, PNG, WebP or GIF pictures; MP4, MOV or WebM videos; MP3, WAV, M4A, AAC or OGG sounds. Pictures up to 25 MB, videos up to 100 MB, sounds up to 50 MB. Some phone videos (HEVC, the iPhone default) may need converting to a standard MP4 before they play everywhere. Over REST, send an Idempotency-Key header (a fresh UUID per new import), so a retry never stores the file twice.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.media.import","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_media action=import_url","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"description":"A public https link to the file.","type":"string","maxLength":2048,"pattern":"^https:\\/\\/[^\\s]+$"},"name":{"description":"A name for the file. Default: the file's own name.","type":"string","minLength":1,"maxLength":200},"projectId":{"description":"Optional. The project these files are for. Later, list with this projectId to find them.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"required":["url"],"additionalProperties":false},"example":{"url":"https://drive.google.com/file/d/1AbCdEfGhIjKlMnOpQrStUvWxYz012345/view?usp=sharing","projectId":"proj_bakery"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"The media id. Other tools take it as mediaId.","type":"string"},"type":{"description":"image, video or audio.","type":"string","enum":["image","video","audio"]},"mimeType":{"description":"The real file type, detected from the file itself.","anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"size":{"description":"Size in bytes.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"url":{"description":"Where the file is stored. Works in AutoClips projects.","type":"string"},"projectId":{"description":"The project it was uploaded for, if any.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"upload = someone uploaded it; ai = AutoClips generated it; library = one of your finished AutoClips videos, brought in for the Video Editor (autoclips_editor import_video).","type":"string","enum":["upload","ai","library"]}},"required":["id","type","mimeType","name","size","url","projectId","createdAt","source"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"id":"66f7c0ffee00000000000001","type":"image","mimeType":"image/png","name":"bakery-front.png","size":482113,"url":"https://media.autoclips.app/clips/character-explainer/5dc8655f-0000-4000-8000-000000000000/api/0b6f3a52-6f7e-4d9c-9d0e-3f4f0b1c2d3e.png","projectId":"proj_bakery","createdAt":"2026-09-28T10:00:00.000Z","source":"upload"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/media/upload-links":{"post":{"operationId":"shared_media_upload_links_create","summary":"Make a one-time upload link for the user. They open it on any device and drop files into your library.","description":"Give the user this link; they open it on any device, drop files, then tell you when done; then call upload_link_status with the linkId, or list with the projectId. The link works once (one batch of up to 10 files, 95 MB in total) and for 15 minutes. Pictures up to 25 MB, videos up to 95 MB, sounds up to 50 MB. Some phone videos (HEVC, the iPhone default) may need converting to a standard MP4 before they play everywhere. It stops working if the key or app that made it is removed. An account can have 20 unused links at once.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.media.upload_links.create","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_media action=upload_link","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"description":"Optional. The project these files are for. Later, list with this projectId to find them.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"note":{"description":"A short line shown on the upload page, for example \"Photos for the bakery video\".","type":"string","minLength":1,"maxLength":120}},"additionalProperties":false},"example":{"projectId":"proj_bakery","note":"Photos for the bakery video"}}}},"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"linkId":{"description":"Use it with upload_link_status.","type":"string"},"url":{"description":"Give this to the user exactly as it is, including the part after #. It works once, for 15 minutes, on any device.","type":"string"},"expiresAt":{"type":"string"},"maxFiles":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["linkId","url","expiresAt","maxFiles","projectId","note"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"linkId":"upl_1a2b3c4d5e6f7a8b","url":"https://app.autoclips.app/upload#Qm9vZ3VzRXhhbXBsZVRva2VuTm90QVJlYWxPbmVfMTIz","expiresAt":"2026-09-28T10:15:00.000Z","maxFiles":10,"projectId":"proj_bakery","note":"Photos for the bakery video"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/media/upload-links/{linkId}":{"get":{"operationId":"shared_media_upload_links_get","summary":"Check an upload link: waiting, uploading, uploaded, failed, expired or revoked, and the files that came in.","description":"Check an upload link: waiting, uploading, uploaded, failed, expired or revoked, and the files that came in.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.media.upload_links.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_media action=upload_link_status","parameters":[{"name":"linkId","in":"path","required":true,"schema":{"description":"The linkId you got back from upload_link.","type":"string","pattern":"^upl_[a-f0-9]{16}$"},"description":"The linkId you got back from upload_link.","example":"upl_1a2b3c4d5e6f7a8b"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"linkId":{"type":"string"},"status":{"description":"waiting = not used yet; uploading = being saved now; uploaded = files are in, see media; failed = saving did not finish, make a new link; expired = 15 minutes passed unused; revoked = the key or app that made it was removed.","type":"string","enum":["waiting","uploading","uploaded","failed","expired","revoked"]},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"usedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"maxFiles":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"media":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The media id. Other tools take it as mediaId.","type":"string"},"type":{"description":"image, video or audio.","type":"string","enum":["image","video","audio"]},"mimeType":{"description":"The real file type, detected from the file itself.","anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"size":{"description":"Size in bytes.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"url":{"description":"Where the file is stored. Works in AutoClips projects.","type":"string"},"projectId":{"description":"The project it was uploaded for, if any.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"upload = someone uploaded it; ai = AutoClips generated it; library = one of your finished AutoClips videos, brought in for the Video Editor (autoclips_editor import_video).","type":"string","enum":["upload","ai","library"]}},"required":["id","type","mimeType","name","size","url","projectId","createdAt","source"],"additionalProperties":false}}},"required":["linkId","status","expiresAt","usedAt","projectId","note","maxFiles","media"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"linkId":"upl_1a2b3c4d5e6f7a8b","status":"uploaded","expiresAt":"2026-09-28T10:15:00.000Z","usedAt":"2026-09-28T10:03:12.000Z","projectId":"proj_bakery","note":"Photos for the bakery video","maxFiles":10,"media":[{"id":"66f7c0ffee00000000000001","type":"image","mimeType":"image/png","name":"bakery-front.png","size":482113,"url":"https://media.autoclips.app/clips/character-explainer/5dc8655f-0000-4000-8000-000000000000/api/0b6f3a52-6f7e-4d9c-9d0e-3f4f0b1c2d3e.png","projectId":"proj_bakery","createdAt":"2026-09-28T10:00:00.000Z","source":"upload"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/media/{mediaId}":{"get":{"operationId":"shared_media_get","summary":"Get one picture, video or sound from your library by its id.","description":"Get one picture, video or sound from your library by its id.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.media.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_media action=get","parameters":[{"name":"mediaId","in":"path","required":true,"schema":{"description":"The media id, from list, upload or import.","type":"string","pattern":"^[a-fA-F0-9]{24}$"},"description":"The media id, from list, upload or import.","example":"66f7c0ffee00000000000001"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"The media id. Other tools take it as mediaId.","type":"string"},"type":{"description":"image, video or audio.","type":"string","enum":["image","video","audio"]},"mimeType":{"description":"The real file type, detected from the file itself.","anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"size":{"description":"Size in bytes.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"url":{"description":"Where the file is stored. Works in AutoClips projects.","type":"string"},"projectId":{"description":"The project it was uploaded for, if any.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"upload = someone uploaded it; ai = AutoClips generated it; library = one of your finished AutoClips videos, brought in for the Video Editor (autoclips_editor import_video).","type":"string","enum":["upload","ai","library"]}},"required":["id","type","mimeType","name","size","url","projectId","createdAt","source"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"id":"66f7c0ffee00000000000001","type":"image","mimeType":"image/png","name":"bakery-front.png","size":482113,"url":"https://media.autoclips.app/clips/character-explainer/5dc8655f-0000-4000-8000-000000000000/api/0b6f3a52-6f7e-4d9c-9d0e-3f4f0b1c2d3e.png","projectId":"proj_bakery","createdAt":"2026-09-28T10:00:00.000Z","source":"upload"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"shared_media_delete","summary":"Delete a file from your library. Projects that already use it may stop rendering.","description":"Removes the file from your library. A file you uploaded is also deleted from storage; a generated file is only removed from the library. Projects that already use it may no longer render.\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["Account, media and publishing"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"shared.media.delete","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_media action=delete","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"mediaId","in":"path","required":true,"schema":{"description":"The media id, from list, upload or import.","type":"string","pattern":"^[a-fA-F0-9]{24}$"},"description":"The media id, from list, upload or import.","example":"66f7c0ffee00000000000001"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"},"fileDeleted":{"description":"True when the stored file itself was deleted (your own uploads).","type":"boolean"}},"required":["id","deleted","fileDeleted"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"id":"66f7c0ffee00000000000001","deleted":true,"fileDeleted":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/options":{"get":{"operationId":"shared_options_get","summary":"Every choice a product offers: allowed values, defaults, credit costs, plans and an example.","description":"Lists the options of a product (styles, models, caption looks, durations, voice settings and so on). Each option has an id, a label, a plain description, its allowed values (each with a label, a description, any credit effect and the plans that may use it), the default and an example. Send a value under the option id, unless the option has `fields`: then send it under the field each operation names, as the type it names (for example the soundEffect option is sent as `effectId`, and characterPosition as `characters[].position`). Pass `product` for one product: you get its options and then the shared ones its fields also use (key permissions, media types, page size). Add `option` for one setting; it is looked up in that product first, then in the shared options. Without `product` you get every product that has published options. Needs the `read` permission.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.options.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_options action=get","parameters":[{"name":"product","in":"query","required":false,"schema":{"description":"Product: Which part of AutoClips a request is about.\nChoices:\n- shared — Account, media and publishing: Your account, credits, media, keys and publishing.\n- v3 — AutoClips V3 (cinematic stories): Cinematic story videos made from a topic or a script.\n- ce — Character Explainer: Famous characters explain a topic in scenes.\n- studio — 3D Animated Studio 2.0: Animated films with your own characters.\n- stickman — Stickman videos (Explainer, Skit, Story): Stick-figure videos: Explainer, Skit and Story (You Decide, True Story), their series and automations.\n- fruit — Fruit AI Stories and Animal Stories: Short dramas acted by fruit-headed or animal-headed people, alone or as a series of parts, and their automations.\nDefault: Every product (leave it out).","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"example":"shared"},{"name":"option","in":"query","required":false,"schema":{"description":"One option id, for example \"scopes\" or \"mediaType\". With product, that product is searched first, then the shared options. Without product, every product is searched.","type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-zA-Z0-9_]*$"},"description":"One option id, for example \"scopes\" or \"mediaType\". With product, that product is searched first, then the shared options. Without product, every product is searched.","example":"scopes"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"catalogs":{"description":"One entry per catalog: the product asked about, then the shared options its fields also use. With `option`, a single entry holding only that option.","type":"array","items":{"type":"object","properties":{"product":{"type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"title":{"type":"string"},"description":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["enum","number","boolean","text","list"]},"values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"creditsEffect":{"type":"string"},"plans":{"type":"array","items":{"type":"string"}},"default":{"type":"boolean"},"meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","label","description"],"additionalProperties":false}},"min":{"type":"number"},"max":{"type":"number"},"step":{"type":"number"},"unit":{"type":"string"},"default":{"description":"The value used when the field is left out. null: see defaultLabel, or, without one, the user must choose."},"defaultLabel":{"description":"What leaving the field out means, when default is null (for example \"No cap\").","type":"string"},"example":{},"appliesTo":{"type":"array","items":{"type":"string"}},"group":{"type":"string"},"fields":{"description":"Where each operation that uses this option takes its value, given only when that is not simply a field named like the option taking a value as listed. Send the value under `field`, as `type`. Empty when no field takes the value as it is (for example a count that follows how many items you send). Without `fields`, send the value under the option id.","type":"array","items":{"type":"object","properties":{"operation":{"description":"The operation id.","type":"string"},"field":{"description":"Where the value goes in its input: a field name, or a path such as \"characters[].position\" (a field of each item in the characters list).","type":"string"},"type":{"description":"What the field takes, as JSON: for example \"string\", \"number\", \"integer\", \"boolean\" or \"array of string\". A value id such as \"60\" is sent as 60 when this says number or integer.","type":"string"}},"required":["operation","field","type"],"additionalProperties":false}}},"required":["id","label","description","type","default","example"],"additionalProperties":false}}},"required":["product","title","options"],"additionalProperties":false}}},"required":["catalogs"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"catalogs":[{"product":"shared","title":"Account, media and keys","description":"Choices that apply across AutoClips: which product to ask about, key permissions, media files and list sizes.","options":[{"id":"scopes","label":"Key permissions","description":"What an API key (or a connected AI app) is allowed to do. A request that needs a permission the key lacks is refused with 403.","type":"list","values":[{"id":"read","label":"See your projects and videos","description":"List and open projects, videos, media, characters, voices, credits and job status.","default":true},{"id":"edit","label":"Change your projects","description":"Create drafts and change scripts, scenes, timelines, captions and settings. Free changes only.","default":true},{"id":"spend","label":"Spend credits","description":"Run anything that costs credits: scripts, pictures, voice, clips, renders. Every spend still needs a quote you approved or a max_credits limit.","default":true},{"id":"delete","label":"Delete things","description":"Delete projects, media, characters and voices.","default":true},{"id":"publish","label":"Post to your social accounts","description":"Publish finished videos to the social accounts you connected.","default":true}],"min":1,"max":5,"default":["read","edit","spend","delete","publish"],"example":["read","edit"],"appliesTo":["shared.keys.create","shared.keys.update"],"group":"Keys"}]}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/outros":{"post":{"operationId":"shared_outros_create","summary":"Make an outro (end card) from a design, your words, handles and logo. Up to 50 in your library.","description":"Makes a new outro in your library, exactly as saving one in the outro editor on the website does. Pick a design (template), then the words (copy), the look, the frame shape, how long it shows and what happens to the music. A logo or product picture is a picture in your media library, by media id. Link one of your brands (brandId) to fill the card from it (fromBrand) and keep it in step (syncFromBrand, on by default only with fromBrand). The card must show something: a headline, website, handle, name or logo. For a \"Your video\" outro, use upload_video instead. Free on every plan, up to 50 outros. Without an Idempotency-Key (AI apps), the same outro asked for again within 10 minutes answers the one already made (alreadyMade: true).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.outros.create","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_outros action=create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"What you call this outro in your library (1 to 60 characters). It is not shown on the card.","type":"string","minLength":1,"maxLength":60,"pattern":"^[^\\u0000-\\u001f\\u007f‪-‮⁦-⁩]*$"},"template":{"description":"The card design. \"plate\" (Plate): Logo, name and website on a flat plate. The classic end slate. Shows headline, url, logo; 2 s by default. \"subscribe\" (Subscribe): Round avatar, one line, and a Subscribe pill that pops in. Shows headline, action, handles, logo; 3 s by default. \"follow\" (Follow): Headline over a row of handle chips that arrive one by one. Shows headline, handles, logo; 3 s by default. \"visit\" (Visit): The website types itself in under the headline. Shows headline, action, url, logo; 3 s by default. \"product\" (Product): A product image beside the name and an action pill. Shows headline, action, url, productImage, logo; 4 s by default. \"signoff\" (Sign-off): Two lines of text and a handle. No logo needed. Shows headline, tagline, handles; 2 s by default. \"kinetic\" (Kinetic): Headline words slam in one at a time, then the action pill lands. Shows headline, action, url, logo; 3 s by default. \"orbit\" (Orbit): Your logo in the centre with handles orbiting around it. Shows headline, action, handles, logo; 4 s by default. \"ticker\" (Ticker): A marquee band of your URL runs behind a bold headline. Shows headline, action, url, logo; 3 s by default. \"custom\" (Your video) plays your own clip: make one with upload_video. Default: \"plate\".","type":"string","enum":["plate","subscribe","follow","visit","product","signoff","kinetic","orbit","ticker","custom"]},"aspectRatio":{"description":"The frame shape the card is made for: \"9:16\" (Vertical, Shorts, Reels, TikTok), \"16:9\" (Landscape, YouTube), \"1:1\" (Square, Feed posts). A card still fits any video. Default: \"9:16\".","type":"string","enum":["9:16","16:9","1:1"]},"durationSeconds":{"description":"How long the card shows, in whole seconds (1 to 6). A recorded spoken line can keep it up a little longer. Not for \"Your video\" outros, which last as long as their clip. Default: the design's own length.","type":"integer","minimum":1,"maximum":6},"sound":{"description":"\"continue-music\": The video's music keeps playing and fades out on the last frame. \"silent\": Music stops when the outro starts. Default: \"continue-music\".","type":"string","enum":["continue-music","silent"]},"copy":{"description":"The words on the card. Every field is optional; update changes only the fields you send.","type":"object","properties":{"headline":{"description":"The big line on the card (up to 48 characters). \"\" clears it.","type":"string","maxLength":48,"pattern":"^[^\\u0000-\\u001f\\u007f‪-‮⁦-⁩]*$"},"action":{"description":"The words on the button (up to 44 characters), for example \"Subscribe\", \"Follow\", \"Visit\", \"Learn more\", \"Sign up\", \"Start free\". \"\" leaves the design's own words.","type":"string","maxLength":44,"pattern":"^[^\\u0000-\\u001f\\u007f‪-‮⁦-⁩]*$"},"url":{"description":"The website shown on the card, as text (for example \"autoclips.app\", up to 64 characters). It is only shown, never visited. \"\" clears it.","type":"string","maxLength":64,"pattern":"^[^\\s\\u0000-\\u001f\\u007f]*$"},"tagline":{"description":"A second, smaller line (up to 72 characters; the \"signoff\" design shows it). \"\" clears it.","type":"string","maxLength":72,"pattern":"^[^\\u0000-\\u001f\\u007f‪-‮⁦-⁩]*$"},"name":{"description":"The name shown on the card, such as your brand or channel (up to 60 characters). \"\" clears it.","type":"string","maxLength":60,"pattern":"^[^\\u0000-\\u001f\\u007f‪-‮⁦-⁩]*$"},"handles":{"description":"Social handles by platform (instagram, tiktok, youtube, twitter). Send only the ones to set or remove; the others stay.","type":"object","properties":{"instagram":{"description":"Your Instagram handle, like \"@mybrand\" (up to 32 characters). \"\" removes it.","type":"string","maxLength":32,"pattern":"^@?[^\\s@/\\\\?#:\\u0000-\\u001f\\u007f]*$"},"tiktok":{"description":"Your TikTok handle, like \"@mybrand\" (up to 32 characters). \"\" removes it.","type":"string","maxLength":32,"pattern":"^@?[^\\s@/\\\\?#:\\u0000-\\u001f\\u007f]*$"},"youtube":{"description":"Your YouTube handle, like \"@mybrand\" (up to 32 characters). \"\" removes it.","type":"string","maxLength":32,"pattern":"^@?[^\\s@/\\\\?#:\\u0000-\\u001f\\u007f]*$"},"twitter":{"description":"Your X handle, like \"@mybrand\" (up to 32 characters). \"\" removes it.","type":"string","maxLength":32,"pattern":"^@?[^\\s@/\\\\?#:\\u0000-\\u001f\\u007f]*$"}},"additionalProperties":false}},"additionalProperties":false},"look":{"description":"How the card looks. Every field is optional; update changes only the fields you send.","type":"object","properties":{"background":{"description":"The card's background: \"dark\" (Dark), \"light\" (Light), \"brand\" (Brand colour). Default: \"dark\".","type":"string","enum":["dark","light","brand"]},"accent":{"description":"The accent colour, as \"#rrggbb\" (buttons, chips, and the \"brand\" background). Default: \"#3fd8e2\".","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"font":{"description":"The lettering: \"default\" (Default), \"notosans\" (Noto Sans), \"bandico\" (Bandico), \"montserrat\" (Montserrat), \"delius\" (Delius), \"monsieur\" (Monsieur), \"bebas\" (Bebas Neue), \"anton\" (Anton), \"oswald\" (Oswald), \"poppins\" (Poppins), \"roboto\" (Roboto), \"urbanist\" (Urbanist), \"lato\" (Lato), \"bangers\" (Bangers), \"blackops\" (Black Ops), \"marker\" (Marker). \"default\" uses the video's own font.","type":"string","enum":["default","notosans","bandico","montserrat","delius","monsieur","bebas","anton","oswald","poppins","roboto","urbanist","lato","bangers","blackops","marker"]},"showLogo":{"description":"Whether the logo shows (when there is one).","type":"boolean"},"logoScale":{"description":"Logo size: 0.6 to 2.2 times the design's own size (1 = as designed).","type":"number","minimum":0.6,"maximum":2.2},"headlineScale":{"description":"Headline size: 0.7 to 1.6 times the design's own size (1 = as designed).","type":"number","minimum":0.7,"maximum":1.6},"actionScale":{"description":"Button text size: 0.7 to 1.6 times the design's own size (1 = as designed).","type":"number","minimum":0.7,"maximum":1.6},"logoMediaId":{"description":"The logo: a picture in your media library (its media id from autoclips_media), or \"none\" to remove it.","type":"string","pattern":"^([a-fA-F0-9]{24}|none)$"},"productImageMediaId":{"description":"The product picture (the \"product\" design shows it): a picture in your media library (its media id from autoclips_media), or \"none\" to remove it.","type":"string","pattern":"^([a-fA-F0-9]{24}|none)$"}},"additionalProperties":false},"brandId":{"description":"One of your brands (made on the AutoClips website under Brands), or \"none\" for no brand. A linked brand can fill the card and keep it in step with the brand (syncFromBrand).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"fromBrand":{"description":"true: fill the name, website, handles, logo and product picture from the brand (brandId) first; anything you send in copy or look wins. Default: false.","type":"boolean"},"syncFromBrand":{"description":"true: when a video renders, the card uses the linked brand's current name, website, handles and logo wherever the brand has them, in place of your own. Needs a brand. Default on create: true when you fill the card from the brand (fromBrand), otherwise false. On update it stays as saved (linking a brand to an outro that had none leaves it off).","type":"boolean"}},"additionalProperties":false},"example":{"name":"Follow us","template":"follow","copy":{"headline":"More stories every week","name":"Lighthouse Tales","handles":{"instagram":"@lighthousetales","tiktok":"@lighthousetales"}}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"outro":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"template":{"description":"The design id (see create).","type":"string"},"templateLabel":{"type":"string"},"aspectRatio":{"type":"string"},"durationSeconds":{"description":"How long the card lasts (a \"Your video\" outro: its clip's length).","type":"number"},"holdSeconds":{"description":"How long it really stays on screen: a spoken line can keep it up longer.","type":"number"},"sound":{"type":"string"},"brand":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"syncing":{"description":"The card takes the brand's current details when a video renders.","type":"boolean"},"missing":{"description":"The linked brand no longer exists.","type":"boolean"}},"required":["id","name","syncing","missing"],"additionalProperties":false},{"type":"null"}]},"copy":{"description":"The words as you set them.","type":"object","properties":{"headline":{"type":"string"},"action":{"type":"string"},"url":{"type":"string"},"tagline":{"type":"string"},"name":{"type":"string"},"handles":{"description":"Handle per platform; \"\" when not set.","type":"object","properties":{"instagram":{"type":"string"},"tiktok":{"type":"string"},"youtube":{"type":"string"},"twitter":{"type":"string"}},"required":["instagram","tiktok","youtube","twitter"],"additionalProperties":false}},"required":["headline","action","url","tagline","name","handles"],"additionalProperties":false},"onCard":{"description":"What the card shows: your words with the linked brand's details filled in (the website without https://).","type":"object","properties":{"headline":{"type":"string"},"action":{"type":"string"},"url":{"type":"string"},"tagline":{"type":"string"},"name":{"type":"string"},"handles":{"description":"Handle per platform; \"\" when not set.","type":"object","properties":{"instagram":{"type":"string"},"tiktok":{"type":"string"},"youtube":{"type":"string"},"twitter":{"type":"string"}},"required":["instagram","tiktok","youtube","twitter"],"additionalProperties":false}},"required":["headline","action","url","tagline","name","handles"],"additionalProperties":false},"look":{"type":"object","properties":{"background":{"type":"string"},"accent":{"type":"string"},"font":{"type":"string"},"showLogo":{"type":"boolean"},"logoScale":{"type":"number"},"headlineScale":{"type":"number"},"actionScale":{"type":"number"},"hasLogo":{"type":"boolean"},"logoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"hasProductImage":{"type":"boolean"},"productImageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["background","accent","font","showLogo","logoScale","headlineScale","actionScale","hasLogo","logoUrl","hasProductImage","productImageUrl"],"additionalProperties":false},"voice":{"type":"object","properties":{"on":{"description":"The recorded line plays.","type":"boolean"},"recorded":{"type":"boolean"},"line":{"type":"string"},"speaker":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"type":"number"}},"required":["on","recorded","line","speaker","durationSeconds"],"additionalProperties":false},"video":{"description":"The clip of a \"Your video\" outro; null when there is none.","anyOf":[{"type":"object","properties":{"url":{"type":"string"},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"hasAudio":{"type":"boolean"},"fit":{"type":"string"},"keepSound":{"type":"boolean"}},"required":["url","posterUrl","durationSeconds","width","height","hasAudio","fit","keepSound"],"additionalProperties":false},{"type":"null"}]},"usedCount":{"description":"How many videos have rendered with it.","type":"number"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"edit":{"description":"Open it in the outro editor on the AutoClips website.","type":"string"}},"required":["edit"],"additionalProperties":false}},"required":["id","name","template","templateLabel","aspectRatio","durationSeconds","holdSeconds","sound","brand","copy","onCard","look","voice","video","usedCount","createdAt","updatedAt","links"],"additionalProperties":false},"alreadyMade":{"description":"True when this exact outro was made in the last 10 minutes: that one is the answer and nothing new was made.","type":"boolean"}},"required":["outro","alreadyMade"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"outro":{"id":"5f0c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a11","name":"Follow us","template":"follow","templateLabel":"Follow","aspectRatio":"9:16","durationSeconds":3,"holdSeconds":3,"sound":"continue-music","brand":null,"copy":{"headline":"More stories every week","action":"Follow","url":"","tagline":"","name":"Lighthouse Tales","handles":{"instagram":"lighthousetales","tiktok":"lighthousetales","youtube":"","twitter":""}},"onCard":{"headline":"More stories every week","action":"Follow","url":"","tagline":"","name":"Lighthouse Tales","handles":{"instagram":"lighthousetales","tiktok":"lighthousetales","youtube":"","twitter":""}},"look":{"background":"dark","accent":"#3fd8e2","font":"default","showLogo":true,"logoScale":1,"headlineScale":1,"actionScale":1,"hasLogo":false,"logoUrl":null,"hasProductImage":false,"productImageUrl":null},"voice":{"on":false,"recorded":false,"line":"","speaker":null,"durationSeconds":0},"video":null,"usedCount":4,"createdAt":"2026-09-20T10:00:00.000Z","updatedAt":"2026-09-28T09:00:00.000Z","links":{"edit":"https://app.autoclips.app/outros/5f0c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a11"}},"alreadyMade":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"shared_outros_list","summary":"Your outro library: the end cards you can add after a video.","description":"Lists the outros you made on the AutoClips website (Outros): end cards with your handles, website, logo or your own clip. Up to 50. Use an id with studio_finish outro. Make, change or delete them with the other autoclips_outros actions, or on the website (Outros).\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.outros.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_outros action=list","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"outros":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"template":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"aspectRatio":{"anyOf":[{"type":"string"},{"type":"null"}]},"brand":{"anyOf":[{"type":"string"},{"type":"null"}]},"headline":{"anyOf":[{"type":"string"},{"type":"null"}]},"usedCount":{"type":"number"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","template","durationSeconds","aspectRatio","brand","headline","usedCount","updatedAt"],"additionalProperties":false}},"limit":{"type":"number"}},"required":["outros","limit"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/outros/video":{"post":{"operationId":"shared_outros_upload_video","summary":"Make a \"Your video\" outro from a video in your media library, or put a new clip on an outro. Answers with a job.","description":"Your own clip becomes the end card: it plays as it is after the last scene. The video must already be in your media library (bring it in with autoclips_media upload_link or import_url), MP4, MOV or WebM, 30 seconds or shorter (a clip a moment longer is trimmed), up to 120 MB. It is prepared exactly like an upload in the outro editor: made safe to play in every video, with a still picture for the library. Without outroId a new outro is made; with outroId that outro switches to \"Your video\" with this clip. The outro takes the clip's frame shape, and the video's music stops under a clip whose own sound plays (with keepClipSound false the music plays on). It takes up to a few minutes, so it answers with a job: follow it with autoclips_jobs get; its result has the outro. One clip at a time per account. Free. Without an Idempotency-Key (AI apps), asking for the same clip again within 10 minutes hands back that job, while it runs or while its outro still plays that clip.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.outros.upload_video","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_outros action=upload_video","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mediaId":{"description":"A video in your media library (autoclips_media list, upload_link or import_url): MP4, MOV or WebM, 30 seconds or shorter, up to 120 MB.","type":"string","pattern":"^[a-fA-F0-9]{24}$"},"outroId":{"description":"The outro id: from autoclips_outros list (REST GET /v1/outros) or from create.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"name":{"description":"What you call this outro in your library (1 to 60 characters). It is not shown on the card.","type":"string","minLength":1,"maxLength":60,"pattern":"^[^\\u0000-\\u001f\\u007f‪-‮⁦-⁩]*$"},"fit":{"description":"For \"Your video\" outros, when the clip's shape differs from the video's: \"contain\" (Fit): The whole clip shows, with black bars when the shapes differ. \"cover\" (Fill): The clip fills the frame; the edges are cropped when the shapes differ. Default: \"contain\".","type":"string","enum":["contain","cover"]},"keepClipSound":{"description":"For \"Your video\" outros: play the clip's own sound (when it has one). Default: true. The video's music follows it: the music stops under the clip's own sound and plays on under a muted clip (on update, unless you send sound too).","type":"boolean"}},"required":["mediaId"],"additionalProperties":false},"example":{"mediaId":"66f7c0ffee00000000000005","name":"Studio sign-off"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"started":{"type":"boolean"},"reused":{"description":"True when this is the job of the same clip asked for moments ago: nothing new was started.","type":"boolean"},"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"outroId":{"description":"The outro that gets the clip; null for a new one (its id is in the job's result).","anyOf":[{"type":"string"},{"type":"null"}]},"message":{"type":"string"}},"required":["started","reused","job","outroId","message"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"started":true,"reused":false,"job":{"id":"job_0192f3a4b5c6d7e8f9a0b1c2","product":"shared","kind":"shared.outro_video","resource":{"type":"media","id":"66f7c0ffee00000000000005"},"status":"running","step":"Preparing your clip","progress":null,"result":null,"error":null,"createdAt":"2026-09-29T10:00:00.000Z","updatedAt":"2026-09-29T10:00:00.000Z","finishedAt":null,"poll_after_seconds":10},"outroId":null,"message":"Preparing the clip for a new outro."}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/outros/{outroId}":{"get":{"operationId":"shared_outros_get","summary":"One outro with every setting: its design, words, handles, look, sound, spoken line and clip.","description":"Shows one outro from your library with every setting, what the card really shows once your brand's details are filled in (onCard), and a link to edit it on the website.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.outros.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_outros action=get","parameters":[{"name":"outroId","in":"path","required":true,"schema":{"description":"The outro id: from autoclips_outros list (REST GET /v1/outros) or from create.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The outro id: from autoclips_outros list (REST GET /v1/outros) or from create.","example":"5f0c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a11"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"outro":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"template":{"description":"The design id (see create).","type":"string"},"templateLabel":{"type":"string"},"aspectRatio":{"type":"string"},"durationSeconds":{"description":"How long the card lasts (a \"Your video\" outro: its clip's length).","type":"number"},"holdSeconds":{"description":"How long it really stays on screen: a spoken line can keep it up longer.","type":"number"},"sound":{"type":"string"},"brand":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"syncing":{"description":"The card takes the brand's current details when a video renders.","type":"boolean"},"missing":{"description":"The linked brand no longer exists.","type":"boolean"}},"required":["id","name","syncing","missing"],"additionalProperties":false},{"type":"null"}]},"copy":{"description":"The words as you set them.","type":"object","properties":{"headline":{"type":"string"},"action":{"type":"string"},"url":{"type":"string"},"tagline":{"type":"string"},"name":{"type":"string"},"handles":{"description":"Handle per platform; \"\" when not set.","type":"object","properties":{"instagram":{"type":"string"},"tiktok":{"type":"string"},"youtube":{"type":"string"},"twitter":{"type":"string"}},"required":["instagram","tiktok","youtube","twitter"],"additionalProperties":false}},"required":["headline","action","url","tagline","name","handles"],"additionalProperties":false},"onCard":{"description":"What the card shows: your words with the linked brand's details filled in (the website without https://).","type":"object","properties":{"headline":{"type":"string"},"action":{"type":"string"},"url":{"type":"string"},"tagline":{"type":"string"},"name":{"type":"string"},"handles":{"description":"Handle per platform; \"\" when not set.","type":"object","properties":{"instagram":{"type":"string"},"tiktok":{"type":"string"},"youtube":{"type":"string"},"twitter":{"type":"string"}},"required":["instagram","tiktok","youtube","twitter"],"additionalProperties":false}},"required":["headline","action","url","tagline","name","handles"],"additionalProperties":false},"look":{"type":"object","properties":{"background":{"type":"string"},"accent":{"type":"string"},"font":{"type":"string"},"showLogo":{"type":"boolean"},"logoScale":{"type":"number"},"headlineScale":{"type":"number"},"actionScale":{"type":"number"},"hasLogo":{"type":"boolean"},"logoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"hasProductImage":{"type":"boolean"},"productImageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["background","accent","font","showLogo","logoScale","headlineScale","actionScale","hasLogo","logoUrl","hasProductImage","productImageUrl"],"additionalProperties":false},"voice":{"type":"object","properties":{"on":{"description":"The recorded line plays.","type":"boolean"},"recorded":{"type":"boolean"},"line":{"type":"string"},"speaker":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"type":"number"}},"required":["on","recorded","line","speaker","durationSeconds"],"additionalProperties":false},"video":{"description":"The clip of a \"Your video\" outro; null when there is none.","anyOf":[{"type":"object","properties":{"url":{"type":"string"},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"hasAudio":{"type":"boolean"},"fit":{"type":"string"},"keepSound":{"type":"boolean"}},"required":["url","posterUrl","durationSeconds","width","height","hasAudio","fit","keepSound"],"additionalProperties":false},{"type":"null"}]},"usedCount":{"description":"How many videos have rendered with it.","type":"number"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"edit":{"description":"Open it in the outro editor on the AutoClips website.","type":"string"}},"required":["edit"],"additionalProperties":false}},"required":["id","name","template","templateLabel","aspectRatio","durationSeconds","holdSeconds","sound","brand","copy","onCard","look","voice","video","usedCount","createdAt","updatedAt","links"],"additionalProperties":false}},"required":["outro"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"outro":{"id":"5f0c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a11","name":"Follow us","template":"follow","templateLabel":"Follow","aspectRatio":"9:16","durationSeconds":3,"holdSeconds":3,"sound":"continue-music","brand":null,"copy":{"headline":"More stories every week","action":"Follow","url":"","tagline":"","name":"Lighthouse Tales","handles":{"instagram":"lighthousetales","tiktok":"lighthousetales","youtube":"","twitter":""}},"onCard":{"headline":"More stories every week","action":"Follow","url":"","tagline":"","name":"Lighthouse Tales","handles":{"instagram":"lighthousetales","tiktok":"lighthousetales","youtube":"","twitter":""}},"look":{"background":"dark","accent":"#3fd8e2","font":"default","showLogo":true,"logoScale":1,"headlineScale":1,"actionScale":1,"hasLogo":false,"logoUrl":null,"hasProductImage":false,"productImageUrl":null},"voice":{"on":false,"recorded":false,"line":"","speaker":null,"durationSeconds":0},"video":null,"usedCount":4,"createdAt":"2026-09-20T10:00:00.000Z","updatedAt":"2026-09-28T09:00:00.000Z","links":{"edit":"https://app.autoclips.app/outros/5f0c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a11"}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"shared_outros_update","summary":"Change an outro: send only the settings to change; everything else stays as it is.","description":"Changes the settings you send and keeps every other one, including inside copy (a handle you do not mention stays) and look. Videos rendered from now on use the new card; videos already made keep theirs. brandId \"none\" unlinks the brand; a picture \"none\" removes it. voiceOn switches a line recorded on the website on or off. fit and keepClipSound are for \"Your video\" outros. Refused while a clip is being prepared for this outro (upload_video).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.outros.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_outros action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"What you call this outro in your library (1 to 60 characters). It is not shown on the card.","type":"string","minLength":1,"maxLength":60,"pattern":"^[^\\u0000-\\u001f\\u007f‪-‮⁦-⁩]*$"},"template":{"description":"The card design. \"plate\" (Plate): Logo, name and website on a flat plate. The classic end slate. Shows headline, url, logo; 2 s by default. \"subscribe\" (Subscribe): Round avatar, one line, and a Subscribe pill that pops in. Shows headline, action, handles, logo; 3 s by default. \"follow\" (Follow): Headline over a row of handle chips that arrive one by one. Shows headline, handles, logo; 3 s by default. \"visit\" (Visit): The website types itself in under the headline. Shows headline, action, url, logo; 3 s by default. \"product\" (Product): A product image beside the name and an action pill. Shows headline, action, url, productImage, logo; 4 s by default. \"signoff\" (Sign-off): Two lines of text and a handle. No logo needed. Shows headline, tagline, handles; 2 s by default. \"kinetic\" (Kinetic): Headline words slam in one at a time, then the action pill lands. Shows headline, action, url, logo; 3 s by default. \"orbit\" (Orbit): Your logo in the centre with handles orbiting around it. Shows headline, action, handles, logo; 4 s by default. \"ticker\" (Ticker): A marquee band of your URL runs behind a bold headline. Shows headline, action, url, logo; 3 s by default. \"custom\" (Your video) plays your own clip: make one with upload_video. Default: \"plate\".","type":"string","enum":["plate","subscribe","follow","visit","product","signoff","kinetic","orbit","ticker","custom"]},"aspectRatio":{"description":"The frame shape the card is made for: \"9:16\" (Vertical, Shorts, Reels, TikTok), \"16:9\" (Landscape, YouTube), \"1:1\" (Square, Feed posts). A card still fits any video. Default: \"9:16\".","type":"string","enum":["9:16","16:9","1:1"]},"durationSeconds":{"description":"How long the card shows, in whole seconds (1 to 6). A recorded spoken line can keep it up a little longer. Not for \"Your video\" outros, which last as long as their clip. Default: the design's own length.","type":"integer","minimum":1,"maximum":6},"sound":{"description":"\"continue-music\": The video's music keeps playing and fades out on the last frame. \"silent\": Music stops when the outro starts. Default: \"continue-music\".","type":"string","enum":["continue-music","silent"]},"copy":{"description":"The words on the card. Every field is optional; update changes only the fields you send.","type":"object","properties":{"headline":{"description":"The big line on the card (up to 48 characters). \"\" clears it.","type":"string","maxLength":48,"pattern":"^[^\\u0000-\\u001f\\u007f‪-‮⁦-⁩]*$"},"action":{"description":"The words on the button (up to 44 characters), for example \"Subscribe\", \"Follow\", \"Visit\", \"Learn more\", \"Sign up\", \"Start free\". \"\" leaves the design's own words.","type":"string","maxLength":44,"pattern":"^[^\\u0000-\\u001f\\u007f‪-‮⁦-⁩]*$"},"url":{"description":"The website shown on the card, as text (for example \"autoclips.app\", up to 64 characters). It is only shown, never visited. \"\" clears it.","type":"string","maxLength":64,"pattern":"^[^\\s\\u0000-\\u001f\\u007f]*$"},"tagline":{"description":"A second, smaller line (up to 72 characters; the \"signoff\" design shows it). \"\" clears it.","type":"string","maxLength":72,"pattern":"^[^\\u0000-\\u001f\\u007f‪-‮⁦-⁩]*$"},"name":{"description":"The name shown on the card, such as your brand or channel (up to 60 characters). \"\" clears it.","type":"string","maxLength":60,"pattern":"^[^\\u0000-\\u001f\\u007f‪-‮⁦-⁩]*$"},"handles":{"description":"Social handles by platform (instagram, tiktok, youtube, twitter). Send only the ones to set or remove; the others stay.","type":"object","properties":{"instagram":{"description":"Your Instagram handle, like \"@mybrand\" (up to 32 characters). \"\" removes it.","type":"string","maxLength":32,"pattern":"^@?[^\\s@/\\\\?#:\\u0000-\\u001f\\u007f]*$"},"tiktok":{"description":"Your TikTok handle, like \"@mybrand\" (up to 32 characters). \"\" removes it.","type":"string","maxLength":32,"pattern":"^@?[^\\s@/\\\\?#:\\u0000-\\u001f\\u007f]*$"},"youtube":{"description":"Your YouTube handle, like \"@mybrand\" (up to 32 characters). \"\" removes it.","type":"string","maxLength":32,"pattern":"^@?[^\\s@/\\\\?#:\\u0000-\\u001f\\u007f]*$"},"twitter":{"description":"Your X handle, like \"@mybrand\" (up to 32 characters). \"\" removes it.","type":"string","maxLength":32,"pattern":"^@?[^\\s@/\\\\?#:\\u0000-\\u001f\\u007f]*$"}},"additionalProperties":false}},"additionalProperties":false},"look":{"description":"How the card looks. Every field is optional; update changes only the fields you send.","type":"object","properties":{"background":{"description":"The card's background: \"dark\" (Dark), \"light\" (Light), \"brand\" (Brand colour). Default: \"dark\".","type":"string","enum":["dark","light","brand"]},"accent":{"description":"The accent colour, as \"#rrggbb\" (buttons, chips, and the \"brand\" background). Default: \"#3fd8e2\".","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"font":{"description":"The lettering: \"default\" (Default), \"notosans\" (Noto Sans), \"bandico\" (Bandico), \"montserrat\" (Montserrat), \"delius\" (Delius), \"monsieur\" (Monsieur), \"bebas\" (Bebas Neue), \"anton\" (Anton), \"oswald\" (Oswald), \"poppins\" (Poppins), \"roboto\" (Roboto), \"urbanist\" (Urbanist), \"lato\" (Lato), \"bangers\" (Bangers), \"blackops\" (Black Ops), \"marker\" (Marker). \"default\" uses the video's own font.","type":"string","enum":["default","notosans","bandico","montserrat","delius","monsieur","bebas","anton","oswald","poppins","roboto","urbanist","lato","bangers","blackops","marker"]},"showLogo":{"description":"Whether the logo shows (when there is one).","type":"boolean"},"logoScale":{"description":"Logo size: 0.6 to 2.2 times the design's own size (1 = as designed).","type":"number","minimum":0.6,"maximum":2.2},"headlineScale":{"description":"Headline size: 0.7 to 1.6 times the design's own size (1 = as designed).","type":"number","minimum":0.7,"maximum":1.6},"actionScale":{"description":"Button text size: 0.7 to 1.6 times the design's own size (1 = as designed).","type":"number","minimum":0.7,"maximum":1.6},"logoMediaId":{"description":"The logo: a picture in your media library (its media id from autoclips_media), or \"none\" to remove it.","type":"string","pattern":"^([a-fA-F0-9]{24}|none)$"},"productImageMediaId":{"description":"The product picture (the \"product\" design shows it): a picture in your media library (its media id from autoclips_media), or \"none\" to remove it.","type":"string","pattern":"^([a-fA-F0-9]{24}|none)$"}},"additionalProperties":false},"brandId":{"description":"One of your brands (made on the AutoClips website under Brands), or \"none\" for no brand. A linked brand can fill the card and keep it in step with the brand (syncFromBrand).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"syncFromBrand":{"description":"true: when a video renders, the card uses the linked brand's current name, website, handles and logo wherever the brand has them, in place of your own. Needs a brand. Default on create: true when you fill the card from the brand (fromBrand), otherwise false. On update it stays as saved (linking a brand to an outro that had none leaves it off).","type":"boolean"},"voiceOn":{"description":"Play the spoken line recorded for this outro (true) or not (false). Lines are recorded in the outro editor on the AutoClips website; a \"Your video\" outro has none.","type":"boolean"},"fit":{"description":"For \"Your video\" outros, when the clip's shape differs from the video's: \"contain\" (Fit): The whole clip shows, with black bars when the shapes differ. \"cover\" (Fill): The clip fills the frame; the edges are cropped when the shapes differ. Default: \"contain\".","type":"string","enum":["contain","cover"]},"keepClipSound":{"description":"For \"Your video\" outros: play the clip's own sound (when it has one). Default: true. The video's music follows it: the music stops under the clip's own sound and plays on under a muted clip (on update, unless you send sound too).","type":"boolean"}},"additionalProperties":false},"example":{"copy":{"headline":"New story every Friday","handles":{"youtube":"@lighthousetales"}}}}}},"parameters":[{"name":"outroId","in":"path","required":true,"schema":{"description":"The outro id: from autoclips_outros list (REST GET /v1/outros) or from create.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The outro id: from autoclips_outros list (REST GET /v1/outros) or from create.","example":"5f0c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a11"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"outro":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"template":{"description":"The design id (see create).","type":"string"},"templateLabel":{"type":"string"},"aspectRatio":{"type":"string"},"durationSeconds":{"description":"How long the card lasts (a \"Your video\" outro: its clip's length).","type":"number"},"holdSeconds":{"description":"How long it really stays on screen: a spoken line can keep it up longer.","type":"number"},"sound":{"type":"string"},"brand":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"syncing":{"description":"The card takes the brand's current details when a video renders.","type":"boolean"},"missing":{"description":"The linked brand no longer exists.","type":"boolean"}},"required":["id","name","syncing","missing"],"additionalProperties":false},{"type":"null"}]},"copy":{"description":"The words as you set them.","type":"object","properties":{"headline":{"type":"string"},"action":{"type":"string"},"url":{"type":"string"},"tagline":{"type":"string"},"name":{"type":"string"},"handles":{"description":"Handle per platform; \"\" when not set.","type":"object","properties":{"instagram":{"type":"string"},"tiktok":{"type":"string"},"youtube":{"type":"string"},"twitter":{"type":"string"}},"required":["instagram","tiktok","youtube","twitter"],"additionalProperties":false}},"required":["headline","action","url","tagline","name","handles"],"additionalProperties":false},"onCard":{"description":"What the card shows: your words with the linked brand's details filled in (the website without https://).","type":"object","properties":{"headline":{"type":"string"},"action":{"type":"string"},"url":{"type":"string"},"tagline":{"type":"string"},"name":{"type":"string"},"handles":{"description":"Handle per platform; \"\" when not set.","type":"object","properties":{"instagram":{"type":"string"},"tiktok":{"type":"string"},"youtube":{"type":"string"},"twitter":{"type":"string"}},"required":["instagram","tiktok","youtube","twitter"],"additionalProperties":false}},"required":["headline","action","url","tagline","name","handles"],"additionalProperties":false},"look":{"type":"object","properties":{"background":{"type":"string"},"accent":{"type":"string"},"font":{"type":"string"},"showLogo":{"type":"boolean"},"logoScale":{"type":"number"},"headlineScale":{"type":"number"},"actionScale":{"type":"number"},"hasLogo":{"type":"boolean"},"logoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"hasProductImage":{"type":"boolean"},"productImageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["background","accent","font","showLogo","logoScale","headlineScale","actionScale","hasLogo","logoUrl","hasProductImage","productImageUrl"],"additionalProperties":false},"voice":{"type":"object","properties":{"on":{"description":"The recorded line plays.","type":"boolean"},"recorded":{"type":"boolean"},"line":{"type":"string"},"speaker":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"type":"number"}},"required":["on","recorded","line","speaker","durationSeconds"],"additionalProperties":false},"video":{"description":"The clip of a \"Your video\" outro; null when there is none.","anyOf":[{"type":"object","properties":{"url":{"type":"string"},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"hasAudio":{"type":"boolean"},"fit":{"type":"string"},"keepSound":{"type":"boolean"}},"required":["url","posterUrl","durationSeconds","width","height","hasAudio","fit","keepSound"],"additionalProperties":false},{"type":"null"}]},"usedCount":{"description":"How many videos have rendered with it.","type":"number"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"edit":{"description":"Open it in the outro editor on the AutoClips website.","type":"string"}},"required":["edit"],"additionalProperties":false}},"required":["id","name","template","templateLabel","aspectRatio","durationSeconds","holdSeconds","sound","brand","copy","onCard","look","voice","video","usedCount","createdAt","updatedAt","links"],"additionalProperties":false},"changed":{"description":"The setting groups that were saved.","type":"array","items":{"type":"string"}}},"required":["outro","changed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"outro":{"id":"5f0c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a11","name":"Follow us","template":"follow","templateLabel":"Follow","aspectRatio":"9:16","durationSeconds":3,"holdSeconds":3,"sound":"continue-music","brand":null,"copy":{"headline":"New story every Friday","action":"Follow","url":"","tagline":"","name":"Lighthouse Tales","handles":{"instagram":"lighthousetales","tiktok":"lighthousetales","youtube":"lighthousetales","twitter":""}},"onCard":{"headline":"New story every Friday","action":"Follow","url":"","tagline":"","name":"Lighthouse Tales","handles":{"instagram":"lighthousetales","tiktok":"lighthousetales","youtube":"lighthousetales","twitter":""}},"look":{"background":"dark","accent":"#3fd8e2","font":"default","showLogo":true,"logoScale":1,"headlineScale":1,"actionScale":1,"hasLogo":false,"logoUrl":null,"hasProductImage":false,"productImageUrl":null},"voice":{"on":false,"recorded":false,"line":"","speaker":null,"durationSeconds":0},"video":null,"usedCount":4,"createdAt":"2026-09-20T10:00:00.000Z","updatedAt":"2026-09-28T09:00:00.000Z","links":{"edit":"https://app.autoclips.app/outros/5f0c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a11"}},"changed":["copy"]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"shared_outros_delete","summary":"Delete an outro from your library. This cannot be undone. Not while a video that uses it is being made.","description":"Removes the outro from your library, like Delete on the website: Character Explainer videos that use it get their outro switched off, Studio films and Fruit stories render without it from then on, and videos already made keep their end card. This cannot be undone. Refused while a video that uses it is being made (a Studio film, a Character Explainer or Director Lab render, a Fruit story render) or a clip is being prepared for it. In an AI app it asks first, showing what uses the outro.\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["Account, media and publishing"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"shared.outros.delete","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_outros action=delete","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"outroId","in":"path","required":true,"schema":{"description":"The outro id: from autoclips_outros list (REST GET /v1/outros) or from create.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The outro id: from autoclips_outros list (REST GET /v1/outros) or from create.","example":"5f0c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a11"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"outroId":{"type":"string"},"name":{"type":"string"}},"required":["deleted","outroId","name"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"deleted":true,"outroId":"5f0c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a11","name":"Follow us"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/quotes":{"post":{"operationId":"shared_quotes_create","summary":"Quote a paid operation before running it: its price, its spending limit, or how much a limit grows.","description":"Send the id of a paid operation and the exact input you will send. You get what that operation asks you to approve, in credits, and a quote_token: a price, a spending limit (for work charged step by step as it runs) or how much a spending limit grows. upperBound is true when that is the most you can be charged (a price, or a spending limit that is the most its run can charge) and false when it is not (a spending limit that one step's final cost can run a little over, or how much a spending limit grows, which is only the extra, not what the run is charged). For a spending limit or an increase, the notes say which. Send the same request with that quote_token within 10 minutes to run it. Any change to the input needs a new quote.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.quotes.create","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"description":"The id of a paid operation, for example \"v3.projects.quick_create\".","type":"string","minLength":3,"maxLength":80},"input":{"description":"Exactly the input you will send to that operation, including path fields like projectId.","default":{},"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["operation"],"additionalProperties":false},"example":{"operation":"v3.projects.quick_create","input":{"topic":"How volcanoes form","durationSeconds":60}}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"operation":{"type":"string"},"quote":{"type":"object","properties":{"credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"breakdown":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["label","credits"],"additionalProperties":false}},"upperBound":{"description":"true when credits is the most you can be charged (a price, or a spending limit that is the most its run can charge). false when it is not (a spending limit that one step's final cost can run a little over, or how much a spending limit grows, which is only the extra, not what the run is charged). For a spending limit or an increase, the notes say which.","type":"boolean"},"balance":{"type":"number"},"affordable":{"type":"boolean"},"notes":{"type":"array","items":{"type":"string"}},"important":{"description":"The notes the user must hear before approving (also in notes): what was changed from what you sent, such as the length on a free plan, and what the plan adds, such as the free \"Made with Autoclips.app\" badge. Show them with the price.","type":"array","items":{"type":"string"}}},"required":["credits","breakdown","upperBound"],"additionalProperties":false},"quote_token":{"type":"string"},"expires_in_seconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["operation","quote","quote_token","expires_in_seconds"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"operation":"v3.projects.quick_create","quote":{"credits":3344,"breakdown":[{"label":"Script (standard writer)","credits":25},{"label":"Narration","credits":186},{"label":"Moving clips made straight from the script (AutoClips 1, every scene)","credits":2850},{"label":"Clip planning (5 credits a clip)","credits":190},{"label":"Rendering the finished video (30 credits a minute)","credits":93}],"upperBound":true,"notes":["Expected price: about 1075 credits, if the script runs the 60 s you picked.","What you approve is a spending limit, not the price: the script is charged for the length picked, and the pictures, voice and music for the length the written script really runs, which is often a little longer. 3344 credits is the most it can be charged, for a script as long as the narration may be at this length (about 3 min 6 s).","Your balance (2000 credits) covers the expected price. It does not have to cover the limit: if the script runs longer than your balance can pay for, the pictures, voice and music are charged for the length picked instead.","Charged in two parts while it runs: the script first, then pictures, voice and music, which include rendering the finished video. Rendering again later is free."]},"quote_token":"acmct_…","expires_in_seconds":600}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/social-accounts":{"get":{"operationId":"shared_social_accounts_list","summary":"List the social accounts connected in the app, which ones can be posted to from here, and which platforms are not connected.","description":"The accounts connected in the AutoClips app (YouTube, TikTok, Instagram, Facebook, X, Snapchat), exactly as the app lists them, each with its id (for publish), name, profile and whether it can be posted to from here. Accounts are connected, reconnected and removed only in the AutoClips app (Settings, Social accounts); tell the user to do that there when one is missing or needs reconnecting. Filter to one social profile with profileId. Free.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.social_accounts.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_publish action=accounts","parameters":[{"name":"profileId","in":"query","required":false,"schema":{"description":"Only the accounts of this social profile (the app's \"Posting as\"). Leave it out for every account.","type":"string","pattern":"^[a-f0-9]{24}$"},"description":"Only the accounts of this social profile (the app's \"Posting as\"). Leave it out for every account.","example":"66f1a2b3c4d5e6f708192a40"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"canPublish":{"description":"Whether this account's plan can post from an AI app or the API.","type":"boolean"},"allowedPlatforms":{"type":"array","items":{"type":"string","enum":["youtube","tiktok","instagram","facebook","twitter","snapchat"]}},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"description":"Use it in publish accountIds.","type":"string"},"platform":{"type":"string","enum":["youtube","tiktok","instagram","facebook","twitter","snapchat"]},"platformName":{"type":"string"},"name":{"type":"string"},"connectedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"profileId":{"description":"The social profile (the app's \"Posting as\") it belongs to.","anyOf":[{"type":"string"},{"type":"null"}]},"profileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"canPost":{"description":"Whether publish can post to it from here.","type":"boolean"},"problem":{"description":"Why it cannot be posted to, in plain words.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","platform","platformName","name","connectedAt","profileId","profileName","canPost","problem"],"additionalProperties":false}},"notConnected":{"description":"Platforms the plan allows with no account connected.","type":"array","items":{"type":"string","enum":["youtube","tiktok","instagram","facebook","twitter","snapchat"]}},"note":{"type":"string"}},"required":["canPublish","allowedPlatforms","accounts","notConnected","note"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"canPublish":true,"allowedPlatforms":["youtube","tiktok","instagram","facebook","twitter","snapchat"],"accounts":[{"id":"66f1a2b3c4d5e6f708192a3b","platform":"tiktok","platformName":"TikTok","name":"@lighthousetales","connectedAt":"2026-09-01T10:00:00.000Z","profileId":"66f1a2b3c4d5e6f708192a40","profileName":"Default Profile","canPost":true,"problem":null},{"id":"66f1a2b3c4d5e6f708192a3d","platform":"instagram","platformName":"Instagram","name":"lighthouse.tales","connectedAt":"2026-08-20T10:00:00.000Z","profileId":"66f1a2b3c4d5e6f708192a40","profileName":"Default Profile","canPost":false,"problem":"Instagram says this account was disconnected. Reconnect this Instagram account in the AutoClips app (Settings, Social accounts) to post to it from here."}],"notConnected":["youtube","facebook","twitter","snapchat"],"note":"Post a finished video with publish and the ids of the accounts where canPost is true. Connect or reconnect accounts in the AutoClips app (Settings, Social accounts)."}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/automations":{"get":{"operationId":"stickman_automations_list","summary":"List your Stickman automations with their schedule, series state and daily limit.","description":"Your Stickman automations (Explainer, Skit and Story series), newest first: each one's settings, schedule, posting, where its series is, its daily spending limit and its stats. Automations of other formats are not listed here.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.automations.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_automations action=list","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automations":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"video":{"description":"An Explainer or Skit automation's video.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"series":{"description":"A Story series automation's settings.","type":"object","properties":{"flavor":{"type":"string","enum":["you-decide","true-story"]},"premiseSource":{"type":"string","enum":["ideas","custom"]},"premises":{"type":"array","items":{"type":"string"}},"partsPerSeries":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"afterLastPart":{"type":"string","enum":["new_series","stop"]},"minVoteHours":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"minVotes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"tieBreak":{"type":"string","enum":["coin","a","b"]},"direction":{"anyOf":[{"type":"string"},{"type":"null"}]},"castCharacterIds":{"type":"array","items":{"type":"string"}},"video":{"type":"object","properties":{"lengthSeconds":{"type":"string"},"motion":{"type":"string","enum":["stills","key","full"]},"voiceId":{"type":"string"},"pace":{"type":"string"},"language":{"type":"string"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}]},"captions":{"type":"boolean"},"captionStyle":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"cards":{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},"videoSpeed":{"type":"number"},"artStyle":{"type":"string"},"motionModel":{"description":"The AutoClips model the moving parts film with.","type":"string"},"music":{"type":"object","properties":{"mode":{"type":"string","enum":["bed","library","off"]},"trackId":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["mode","trackId","category"],"additionalProperties":false},"aspect":{"type":"string","const":"9:16"}},"required":["lengthSeconds","motion","voiceId","pace","language","locale","captions","captionStyle","cards","videoSpeed","artStyle","motionModel","music","aspect"],"additionalProperties":false}},"required":["flavor","premiseSource","premises","partsPerSeries","afterLastPart","minVoteHours","minVotes","tieBreak","direction","castCharacterIds","video"],"additionalProperties":false},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"seriesState":{"description":"Where the series is: its number, the last part posted, whether it waits for votes, the last vote.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"watermarkType":{"description":"none, text or image.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"A text watermark's words, or null.","anyOf":[{"type":"string"},{"type":"null"}]},"watermarkTextColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundOpacity":{"description":"0 to 1","type":"number"},"watermarkImageOpacity":{"description":"0.3 to 1","type":"number"},"watermarkVerticalPosition":{"description":"Percent from the top.","type":"number"},"watermarkHorizontalPosition":{"description":"Percent from the left.","type":"number"},"watermarkScale":{"description":"1 is normal.","type":"number"},"watermarkStartSeconds":{"description":"Seconds.","type":"number"},"watermarkEndSeconds":{"description":"Seconds; 0 = to the end.","type":"number"},"outroId":{"description":"Or null.","anyOf":[{"type":"string"},{"type":"null"}]},"partInProgress":{"type":"boolean"},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","status","pauseReason","schedule","topics","publishing","partInProgress","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false}}},"required":["automations"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"automations":[{"id":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d","name":"Midnight Stories","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["18:00"],"videosPerDay":1},"series":{"flavor":"you-decide","premiseSource":"ideas","premises":[],"partsPerSeries":5,"afterLastPart":"new_series","minVoteHours":6,"minVotes":1,"tieBreak":"coin","direction":"Keep it funny.","castCharacterIds":[],"video":{"lengthSeconds":"90","motion":"stills","voiceId":"nPczCjzI2devNBz1zQrb","pace":"brisk","language":"en","locale":null,"captions":true,"captionStyle":null,"cards":{"enabled":true,"theme":null},"videoSpeed":1,"artStyle":"horror","motionModel":"autoclips1","music":{"mode":"bed","trackId":null,"category":null},"aspect":"9:16"}},"topics":{"mode":"category","category":"weird","customTopic":null,"goal":"entertain","goalText":null,"cta":"none","ctaText":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":true,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"seriesState":null,"partInProgress":false,"spendLimit":{"creditsPerDay":2750,"approvedAt":"2026-10-25T09:00:00.000Z"},"estimatedCreditsPerRun":1550,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-10-25T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-10-25T09:00:00.000Z","updatedAt":"2026-10-25T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"stickman_automations_create","summary":"Set up a Stickman automation that makes and posts videos on a schedule, within a daily limit.","description":"Makes a Stickman automation that makes a video at each posting time: an Explainer or a Skit (video) on ideas from a topic (topics), or a Story series (series) where each run makes the next part, You Decide (each part ends on a vote the comments on your posts decide) or True Story (chapter by chapter). What you approve is its daily spending limit: a run that would pass it is skipped and the automation waits for the next day, and a run is settled after it is made, so one step's final cost can run a little over (spendLimitPerDay; left out, one day of runs at their most; for a series, Part 1 of each series also pays for planning it). Every video (every part of a series) can carry your watermark (watermarkType text, or image with watermarkMediaId: one of your pictures) and end on your outro (outroId, paid plans). With publishing, every video is posted automatically: that needs the publish permission, accounts must be yours and platforms on your plan, and the approval names them. A You Decide series whose posting accounts cannot be read for votes (none of TikTok, YouTube, Instagram, Facebook) is made, with a warning: every part then follows the tie rule. Writing its first ideas counts toward the free-AI daily limit. The same request again with the same Idempotency-Key hands back the same automation.\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. Stickman automation day stops before a step that would go past the limit, but one step's final cost can run a little over, so the limit is not the most it can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.automations.create","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_automations action=create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The automation's name: unique on your account, at most 100 characters.","type":"string","minLength":1,"maxLength":100},"schedule":{"description":"When it runs. A new automation needs all three; an update changes only what you send.","type":"object","properties":{"timezone":{"description":"The time zone of the posting times (IANA, for example \"America/New_York\").","type":"string","minLength":1,"maxLength":64},"videosPerDay":{"description":"Videos a day, 1 to 3: one per posting time.","type":"integer","minimum":1,"maximum":3},"times":{"description":"The posting times, one per video a day (\"09:00\", 24-hour).","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}}},"additionalProperties":false},"video":{"description":"The video of an Explainer or Skit automation (not with series). Full motion uses AutoClips clips.","type":"object","properties":{"mode":{"description":"Kind of video: An Explainer or a Skit. Stories start with stickman.story.quick_start or a plan instead.\nChoices:\n- explainer — Explainer: A deadpan narrator walks through an absurd scheme or dark listicle, 30 to 90 seconds.\n- skit — Skit: A ten-second animated gag built on silence, timing and one perfect punchline.\nDefault: explainer.","type":"string","enum":["explainer","skit"]},"angle":{"description":"Angle: The kind of joke the script is built on. Each angle belongs to a mode (meta.modes) and comes with example topics (meta.exampleChips, by mode); Custom takes your own topic in either mode.\nChoices:\n- unethical-money — Unethical Money: An absurd money scheme narrated like a business plan, part N of an endless series.\n- dark-hacks — Dark Hacks: A life-hack listicle where every tip is absurd and the delivery never blinks.\n- psychology — Dark Psychology: The manipulation tricks used on you every day, decoded one by one.\n- tech — Tech & AI: What the machine in your pocket is really doing, briefed like a leak.\n- survival — Dark Survival: Field-manual survival rules that drift from plausible to unhinged.\n- history — Dark History: The hidden, sinister story behind an everyday thing, read like a classified file.\n- custom — Custom: Your own topic, poured into the deadpan explainer grammar. In a Skit: your own premise, run through the skit timing machine.\n- relatable-fear — Relatable Fear: An everyday nighttime fear staged for a jump-laugh.\n- good-bad-news — Good News, Bad News: A two-character dialogue joke where the bad news is the punchline.\n- gaming — Gaming: One last game, and the passage of time that follows.\n- dev-life — Dev Life: The ten-second tragedy of shipping software, staged at one desk.\n- melancholy — Melancholy: A wordless, cinematic sad moment that lands in the chest.\nDefault: Unethical Money for an Explainer, Relatable Fear for a Skit (leave it out).","type":"string","enum":["unethical-money","dark-hacks","psychology","tech","survival","history","custom","relatable-fear","good-bad-news","gaming","dev-life","melancholy"]},"angleRotation":{"description":"fixed keeps the angle; rotate picks a new one each run.","type":"string","enum":["fixed","rotate"]},"lengthSeconds":{"description":"Automation video length: How long each video of an Explainer or Skit automation runs. A Story series automation takes storyLength instead.\nChoices:\n- 30 — 30 seconds: A 30-second video each run. (600 credits base a video (x your plan multiplier))\n- 60 — 1 minute: A 60-second video each run. (1100 credits base a video (x your plan multiplier))\n- 70 — 1.2 minutes: A 70-second video each run. (1250 credits base a video (x your plan multiplier))\nDefault: 60.","type":"string","enum":["30","60","70"]},"motion":{"description":"Explainer motion: How much of an Explainer moves. Leaving it out gives Classic; the website starts a new video on Full Motion. Moving clips are priced by the clip model.\nChoices:\n- classic — Classic: Cinematic zooms sweep across every scene.\n- enhanced — Enhanced: Key scenes come alive with real motion. (Adds 2 clips, each priced by the clip model)\n- full — Full Motion: Every single scene is animated with real motion. (Adds one clip a scene (7 to 18 scenes by length), each priced by the clip model)\nDefault: classic.","type":"string","enum":["classic","enhanced","full"]},"clipModel":{"description":"Clip model: Which model makes an Explainer's moving clips (Enhanced and Full Motion). A clip AutoClips 1 cannot make is made by a backup model, billed at the backup's price.\nChoices:\n- autoclips1 — AutoClips 1: Our main model, 768p. Each clip runs as long as its scene. (Billed by the second, 15 credits a second (5 to 15 seconds a clip): from 80 a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- autoclips1Upscaled — AutoClips 1 1080p Upscaled: AutoClips 1, sharpened to 1080p. (Billed by the second, 20 credits a second (5 to 15 seconds a clip): from 107 a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- autoclips1Light — AutoClips 1 Lite: Half the price, 720p. (Billed by the second, 8 credits a second (5 to 15 seconds a clip): from 43 a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- autoclips1LightHd — AutoClips 1 Lite Full HD: AutoClips 1 Lite drawn at full 1080p. (Billed by the second, 23 credits a second (5 to 15 seconds a clip): from 118 a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- omniMax — Pro Max: Flat price per clip. (805 credits a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- kling3 — Pro: Handles darker scenes. (805 credits a clip (x your plan multiplier), its planning included)\n- autoclips — AutoClips 1 (old name): The old name of autoclips1, still taken. Send autoclips1 instead. (As AutoClips 1)\nDefault: autoclips1.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd","omniMax","kling3","autoclips"]},"voiceId":{"description":"Narrator (Explainer): Who reads an Explainer. meta.sampleUrl plays the same line in each voice.\nChoices:\n- nPczCjzI2devNBz1zQrb — Brian: Deep, relentless deadpan — the signature stickman read.\n- JBFqnCBsd6RMkjVDRZzb — George: British documentary storyteller, brisk and crisp.\n- EXAVITQu4vr4xnSDxMaL — Sarah: Confident, matter-of-fact professional.\n- pNInz6obpgDQGcFmaJgB — Adam: Deep and dominant — cuts through the feed instantly.\n- TxGEqnHWrfWFTfGW9XjX — Josh: Clear, engaging classic narrator.\n- onwK4e9ZLuTAKqWW03F9 — Daniel: Calm broadcast narrator, most measured read.\nDefault: nPczCjzI2devNBz1zQrb.","type":"string","enum":["nPczCjzI2devNBz1zQrb","JBFqnCBsd6RMkjVDRZzb","EXAVITQu4vr4xnSDxMaL","pNInz6obpgDQGcFmaJgB","TxGEqnHWrfWFTfGW9XjX","onwK4e9ZLuTAKqWW03F9"]},"pace":{"description":"Reading pace: How fast the narrator reads. A faster pace fits more words into the same length.\nChoices:\n- relaxed — Relaxed: Everyday speaking pace — easiest to follow.\n- natural — Natural: Steady documentary read.\n- brisk — Brisk: Fast and punchy, still every word clear.\n- rapid — Rapid: Breathless, relentless — the hardest read to follow.\nDefault: brisk.","type":"string","enum":["relaxed","natural","brisk","rapid"]},"skitModel":{"description":"Skit quality: Which quality tier makes a Skit's clips. A Skit has one to four clips; the joke decides how many.\nChoices:\n- omniMax — Pro Max: 8-second clips, the best quality and the fastest to make. (800 credits a clip (x your plan multiplier); a clip it cannot make is made by Pro at 1000)\n- kling3 — Pro: 10-second clips with the most cinematic motion. (1000 credits a clip (x your plan multiplier))\n- veo31lite — Lite: Quick and affordable 8-second clips. (500 credits a clip (x your plan multiplier))\nDefault: omniMax.","type":"string","enum":["omniMax","kling3","veo31lite"]},"language":{"description":"The spoken language code (stickman.capabilities.get lists what each kind of video speaks right now).","type":"string","minLength":2,"maxLength":16},"music":{"description":"The background music.","type":"object","properties":{"mode":{"description":"none, or library: a track or a mood of the music library.","type":"string","enum":["none","library"]},"category":{"description":"A mood of the music library: popular, playful, sneaky, mysterious, epic, chill, upbeat, whimsical, v3-animals, v3-crime, v3-general, v3-history, v3-horror, v3-science, v3-space.","type":"string","enum":["popular","playful","sneaky","mysterious","epic","chill","upbeat","whimsical","v3-animals","v3-crime","v3-general","v3-history","v3-horror","v3-science","v3-space"]},"trackId":{"title":"Music (Stickman videos (Explainer, Skit, Story) option musicTrack)","description":"Music: A music track by id: \"none\" (no music, when an Explainer or Skit is made; a render refuses it, since a render always keeps the video's music: turn a Story's music off with the edit music.none), a track of the music library, or a Story music bed (meta.kind \"bed\"). Links are never taken: the id picks the track.\nChoices: one of 232 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=musicTrack) to see them all.\nDefault: The format's default (Story: the series bed) (leave it out).","type":"string"}},"required":["mode"],"additionalProperties":false},"musicVolumeDb":{"description":"The music's volume under the voice, -30 to 0 dB.","type":"integer","minimum":-30,"maximum":0}},"additionalProperties":false},"topics":{"description":"Where the ideas come from. For a Story series, the theme of new story ideas.","type":"object","properties":{"mode":{"description":"category: ideas on a topic category; custom: ideas on your own theme.","type":"string","enum":["category","custom"]},"category":{"description":"Topic: The theme an automation's ideas are written from.\nChoices:\n- history — History & Ancient Mysteries: Ancient civilizations, historical events, mysteries from the past.\n- science — Science & Nature: Scientific discoveries, natural phenomena, how things work.\n- horror — Horror & Dark Facts: Creepy stories, dark history, unsettling facts.\n- psychology — Psychology & Mind: Human behavior, cognitive science, mental health.\n- tech — Technology & Future: AI, gadgets, future tech, digital world.\n- nature — Animals & Wildlife: Animal facts, wildlife, evolution, ecosystems.\n- money — Money & Finance: Wealth, economics, investing, financial history.\n- health — Health & Body: Human body, nutrition, fitness, medical facts.\n- weird — Weird & Unusual: Strange facts, bizarre stories, oddities.\n- crime — Crime & Mystery: True crime, mysteries, forensics, detective stories.\n- space — Space & Cosmos: Astronomy, space exploration, cosmic mysteries.\n- food — Food & Cooking: Culinary science, food history, cooking facts.\nDefault: weird.","type":"string","enum":["history","science","horror","psychology","tech","nature","money","health","weird","crime","space","food"]},"customTopic":{"description":"Your own theme for new ideas (at most 2,000 characters).","type":"string","minLength":1,"maxLength":2000},"goal":{"description":"Goal: What an automation's videos are written to achieve.\nChoices:\n- entertain — Entertain: This format's default objective.\n- views — Get Views: Maximize video views and reach.\n- followers — Grow Followers: Build audience and follower count.\n- sales — Drive Sales: Promote product/service and drive conversions.\n- awareness — Brand Awareness: Increase brand recognition and visibility.\n- custom — Custom Goal: Define your own goal and strategy.\nDefault: entertain.","type":"string","enum":["entertain","views","followers","sales","awareness","custom"]},"goalText":{"description":"Your own goal, in words (at most 500 characters).","type":"string","minLength":1,"maxLength":500},"cta":{"description":"Call to action: What an automation's videos ask viewers to do at the end.\nChoices:\n- none — No call to action: Let the video end on its own.\n- follow — Follow for More: Ask viewers to follow for similar content.\n- subscribe — Subscribe: Ask viewers to subscribe for more content.\n- share — Share This: Ask viewers to share the video.\n- custom — Custom CTA: Write your own call-to-action.\nDefault: none.","type":"string","enum":["none","follow","subscribe","share","custom"]},"ctaText":{"description":"Your own call to action (at most 200 characters).","type":"string","minLength":1,"maxLength":200}},"additionalProperties":false},"series":{"description":"A Story series automation (instead of video): each run makes the next part of the series. A new series needs flavor.","type":"object","properties":{"flavor":{"description":"you-decide: each part ends on a vote the comments decide; true-story: a real story told chapter by chapter.","type":"string","enum":["you-decide","true-story"]},"premiseSource":{"description":"Where each story comes from: How an automated Story series finds the idea of each new series.\nChoices:\n- ideas — Fresh ideas: New story ideas are written from the topic you pick.\n- custom — Your ideas: Your own story ideas (1 to 10), used in turn.\nDefault: ideas.","type":"string","enum":["ideas","custom"]},"premises":{"description":"Your own story ideas, 10 to 2,000 characters each (at most 10): one per series, in turn.","maxItems":10,"type":"array","items":{"type":"string","minLength":10,"maxLength":2000}},"partsPerSeries":{"description":"Parts per series: How many parts an automated Story series makes before it ends. Each part is one video run. From 2 to 20 parts. Default: 5.","type":"integer","minimum":2,"maximum":20},"afterLastPart":{"description":"After the last part: What an automated Story series does when its last part is posted.\nChoices:\n- new_series — Start a new series: The next run starts Part 1 of a new story.\n- stop — Stop: The automation pauses; resuming it starts a new series.\nDefault: new_series.","type":"string","enum":["new_series","stop"]},"minVoteHours":{"description":"Hours to vote: You Decide series: how long viewers have to vote in the comments before the next part is made. Kept, but unused, for True Story (no vote). From 1 to 48 hours. Default: 6.","type":"integer","minimum":1,"maximum":48},"minVotes":{"description":"Votes needed: You Decide series: the fewest comment votes that decide the next part. With fewer, the tie rule decides. From 1 to 1000 votes. Default: 1.","type":"integer","minimum":1,"maximum":1000},"tieBreak":{"description":"Tie rule: You Decide series: which way the story goes on a tie, or when too few votes came in.\nChoices:\n- coin — Coin toss: A fair coin toss, the same answer every time for the same part.\n- a — Choice A: The first choice of the vote.\n- b — Choice B: The second choice of the vote.\nDefault: coin.","type":"string","enum":["coin","a","b"]},"direction":{"description":"How every part should go, in a sentence (at most 300 characters); null clears it.","anyOf":[{"type":"string","minLength":1,"maxLength":300},{"type":"null"}]},"castCharacterIds":{"description":"Up to 4 of your cast (characterId from stickman_cast list, or a preset) who star in every part.","maxItems":4,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"video":{"description":"Each part's video. Every part is vertical (9:16).","type":"object","properties":{"lengthSeconds":{"description":"Story length: How long a Story (or a Story part) runs. It sets the base price; moving scenes are added on top.\nChoices:\n- 30 — 30 seconds: A 30-second story. (600 credits base (x your plan multiplier))\n- 40 — 40 seconds: A 40-second story. (750 credits base (x your plan multiplier))\n- 50 — 50 seconds: A 50-second story. (950 credits base (x your plan multiplier))\n- 60 — 1 minute: A 60-second story. (1100 credits base (x your plan multiplier))\n- 70 — 1.2 minutes: A 70-second story. (1250 credits base (x your plan multiplier))\n- 80 — 1.3 minutes: A 80-second story. (1400 credits base (x your plan multiplier))\n- 90 — 1.5 minutes: A 90-second story. (1550 credits base (x your plan multiplier))\n- 100 — 1.7 minutes: A 100-second story. (1700 credits base (x your plan multiplier))\n- 110 — 1.8 minutes: A 110-second story. (1850 credits base (x your plan multiplier))\n- 120 — 2 minutes: A 120-second story. (2000 credits base (x your plan multiplier))\nDefault: 90.","type":"string","enum":["30","40","50","60","70","80","90","100","110","120"]},"motion":{"description":"Story motion: How much of a Story moves. Moving scenes are paid plans only and are charged as each one is made, never above the quote's \"at most\". Story options (You Decide, True Story) need Stickman Story switched on for the account; stickman.capabilities.get says what is on right now.\nChoices:\n- stills — Stills: Pictures with camera moves; nothing is animated.\n- key — Key moments: The key moments of the story move. (118 credits a moving scene (a 5-second clip on AutoClips 1; storyMotionModel changes it), at most the quote's cap; plans: paid)\n- full — Full motion: Every picture scene moves. (118 credits a moving scene (a 5-second clip on AutoClips 1; storyMotionModel changes it), at most the quote's cap; plans: paid)\nDefault: stills.","type":"string","enum":["stills","key","full"]},"voiceId":{"description":"Narrator (Story): Who reads a Story. The last 14 (meta.v2Only) need the 20-voice switch; stickman.capabilities.get lists what is offered now. meta.sampleUrl plays a sample.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=storyVoice) to see them all.\nDefault: nPczCjzI2devNBz1zQrb.","type":"string","enum":["nPczCjzI2devNBz1zQrb","JBFqnCBsd6RMkjVDRZzb","EXAVITQu4vr4xnSDxMaL","pNInz6obpgDQGcFmaJgB","TxGEqnHWrfWFTfGW9XjX","onwK4e9ZLuTAKqWW03F9","N2lVS1w4EtoT3dr4eOWO","cjVigY5qzO86Huf0OWal","pqHfZKP75CvOlQylNhV4","iP95p4xoKVk53GoZ742B","TX3LPaxmHKxFdv7VOQHJ","IKne3meq5aSn9XLyUdCD","CwhRBWXzGAHq8TQ4Fs17","pFZP5JQG7iQjIQuC4Bku","Xb7hH8MSUJpSbSDYk0k2","9BWtsMINqrJLrRacOk9x","XrExE9yKIg1WjnnlVkGX","cgSgspJ2msm6clMCkdW9","FGY2WhTYpPnrIDTdsKH5","XB0fDUnXU5powFXDhCwa"]},"pace":{"description":"Reading pace: How fast the narrator reads. A faster pace fits more words into the same length.\nChoices:\n- relaxed — Relaxed: Everyday speaking pace — easiest to follow.\n- natural — Natural: Steady documentary read.\n- brisk — Brisk: Fast and punchy, still every word clear.\n- rapid — Rapid: Breathless, relentless — the hardest read to follow.\nDefault: brisk.","type":"string","enum":["relaxed","natural","brisk","rapid"]},"language":{"title":"Language (Story) (Stickman videos (Explainer, Skit, Story) option storyLanguage)","description":"Language (Story): The language of a Story's narration, cards and captions. Some languages are switched on later than others: a language that is not offered yet is refused with language_not_offered, and stickman.capabilities.get lists what is offered now.\nChoices: one of 94 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=storyLanguage) to see them all.\nDefault: en.","type":"string"},"locale":{"description":"Language variant: Which variant of a Story language to use, for the languages that have one (meta.language). Leave it out for the language's usual variant.\nChoices:\n- es-419 — Spanish (Latin America): Spanish as spoken in Latin America.\n- es-ES — Spanish (Spain): Spanish as spoken in Spain.\n- es-MX — Spanish (Mexico): Spanish as spoken in Mexico.\n- pt-BR — Portuguese (Brazil): Portuguese as spoken in Brazil.\n- pt-PT — Portuguese (Portugal): Portuguese as spoken in Portugal.\n- bn-BD — Bengali (Bangladesh): Bengali as spoken in Bangladesh.\n- bn-IN — Bengali (India): Bengali as spoken in India.\nDefault: The language's usual variant (leave it out).","type":"string","enum":["es-419","es-ES","es-MX","pt-BR","pt-PT","bn-BD","bn-IN"]},"captions":{"description":"Captions on or off.","type":"boolean"},"captionStyle":{"anyOf":[{"description":"The caption look. Leave a key out to keep the format's own.","type":"object","properties":{"highlightStyle":{"description":"Caption look: How the spoken words appear on screen (captionStyle.highlightStyle). The same looks every AutoClips format uses.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionStyle) to see them all.\nDefault: The format's own look (leave it out).","type":"string","enum":["classic","color-only","scale-up","typewriter","progressive","karaoke","bounce","outline","background","shadow-pop","pop-color","neon","underline","gradient","boxed","glow"]},"fontFamily":{"description":"Caption font: The lettering of the captions (captionStyle.fontFamily).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionFont) to see them all.\nDefault: The caption look's own font (leave it out).","type":"string","enum":["Montserrat","BebasNeue","Anton","LeagueSpartan"]},"position":{"description":"Caption position: Where the captions sit (captionStyle.position).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionPosition) to see them all.\nDefault: The format's own position (leave it out).","type":"string","enum":["top","upper-third","center","lower-third","bottom"]},"positionY":{"description":"Where the captions sit, 0 (top) to 100 (bottom); wins over position.","type":"number","minimum":0,"maximum":100},"groupSize":{"description":"Words at a time: How many words the captions show at once (captionStyle.groupSize, sent as a number).\nChoices:\n- 2 — 2 words: Punchy. Reads fastest.\n- 3 — 3 words: The default.\n- 4 — 4 words: Calmer, fewer changes.\nDefault: The caption look's own size (leave it out).","type":"string","enum":["2","3","4"]},"fontSize":{"description":"Caption size, 28 to 110.","type":"integer","minimum":28,"maximum":110},"color":{"description":"Caption colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"highlightColor":{"description":"The spoken word's colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"showBackground":{"description":"A box behind the captions.","type":"boolean"},"backgroundOpacity":{"description":"How solid that box is, 0 to 1.","type":"number","minimum":0,"maximum":1}},"additionalProperties":false},{"type":"null"}]},"cards":{"description":"The on-screen text cards.","type":"object","properties":{"enabled":{"description":"On-screen text cards on or off.","type":"boolean"},"theme":{"anyOf":[{"description":"Text card look: The look of a Story's on-screen text cards and its end card.\nChoices:\n- night — Night: Dark card, green edge.\n- ink — Ink: Dark tiles, pink accents, paper fact cards.\n- clean — Clean: White card, black text.\nDefault: Night for You Decide, Ink for True Story (leave it out).","type":"string","enum":["night","ink","clean"]},{"type":"null"}]}},"additionalProperties":false},"videoSpeed":{"description":"Video speed: How fast the finished video plays, from 1x to 3x in steps of 0.1. The page's quick picks: 1x, 1.1x, 1.2x, 1.3x, 1.5x, 2x, 3x. Free: it changes no price. From 1 to 3 x, in steps of 0.1. Default: 1.","type":"number","minimum":1,"maximum":3,"multipleOf":0.1},"artStyle":{"description":"Art style: The look of the pictures in a Story: the places, the light and the colours. The stick figures stay the same in every style. A next part keeps the style of the part before it. meta.exampleUrl shows the same scene in each style.\nChoices:\n- default — Cinematic: Painted night scenes in teal and warm orange. The classic look. Best for any story.\n- horror — Horror Glow: Dark and creepy, lit by vivid green, red and purple light. Best for scary, survival and mystery stories.\n- noir — Rainy Noir: Rain-soaked streets, hard shadows and cold blue light. Crime and secrets. Best for crime, heists and true stories.\n- sunny — Bright Day: Sunny, colourful and cheerful, like a Saturday-morning cartoon. Best for funny, feel-good and kids stories.\n- epic — Golden Epic: Huge skies, golden sunsets and dust in the air. Feels like a movie. Best for history, war and adventure.\nDefault: default.","type":"string","enum":["default","horror","noir","sunny","epic"]},"motionModel":{"description":"The AutoClips model the moving parts are filmed with (default autoclips1). Only with key or full motion; characters who speak film on AutoClips 1 when a Lite model is picked.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd"]},"music":{"description":"The parts' music: the Story music bed, a library track or mood, or none.","type":"object","properties":{"mode":{"description":"Series music: The music of every part of an automated Story series.\nChoices:\n- bed — Story music: The music bed made for the story kind.\n- library — From the library: A track or a mood of the music library (15 moods).\n- off — No music: The parts have no music.\nDefault: bed.","type":"string","enum":["bed","library","off"]},"trackId":{"anyOf":[{"title":"Music (Stickman videos (Explainer, Skit, Story) option musicTrack)","description":"Music: A music track by id: \"none\" (no music, when an Explainer or Skit is made; a render refuses it, since a render always keeps the video's music: turn a Story's music off with the edit music.none), a track of the music library, or a Story music bed (meta.kind \"bed\"). Links are never taken: the id picks the track.\nChoices: one of 232 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=musicTrack) to see them all.\nDefault: The format's default (Story: the series bed) (leave it out).","type":"string"},{"type":"null"}]},"category":{"anyOf":[{"description":"A mood of the music library: popular, playful, sneaky, mysterious, epic, chill, upbeat, whimsical, v3-animals, v3-crime, v3-general, v3-history, v3-horror, v3-science, v3-space.","type":"string","enum":["popular","playful","sneaky","mysterious","epic","chill","upbeat","whimsical","v3-animals","v3-crime","v3-general","v3-history","v3-horror","v3-science","v3-space"]},{"type":"null"}]}},"required":["mode"],"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"publishing":{"description":"Where each video goes. Switching posting on, changing the posting account or making YouTube videos more public needs the publish permission; only the platforms you send change.","type":"object","properties":{"email":{"description":"Email you when each video is ready.","type":"boolean"},"library":{"description":"Keep each video in My Videos.","type":"boolean"},"tiktok":{"description":"Posting to TikTok.","type":"object","properties":{"enabled":{"description":"Post every video to TikTok.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"youtube":{"description":"Posting to YouTube.","type":"object","properties":{"enabled":{"description":"Post every video to YouTube.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"},"privacy":{"description":"public, unlisted or private (default private; private videos get no comments, so no votes).","type":"string","enum":["public","unlisted","private"]},"categoryId":{"description":"The YouTube category id (2 Autos & Vehicles, 23 Comedy, 27 Education, 24 Entertainment, 1 Film & Animation, 20 Gaming, 26 Howto & Style, 10 Music, 25 News & Politics, 29 Nonprofits & Activism, 22 People & Blogs, 15 Pets & Animals, 28 Science & Technology, 17 Sports, 19 Travel & Events).","type":"string","enum":["1","2","10","15","17","19","20","22","23","24","25","26","27","28","29"]},"useAIMetadata":{"description":"Write the title and description from the video (default true).","type":"boolean"}},"required":["enabled"],"additionalProperties":false},"instagram":{"description":"Posting to Instagram.","type":"object","properties":{"enabled":{"description":"Post every video to Instagram.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"facebook":{"description":"Posting to Facebook.","type":"object","properties":{"enabled":{"description":"Post every video to Facebook.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"twitter":{"description":"Posting to X.","type":"object","properties":{"enabled":{"description":"Post every video to X.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"snapchat":{"description":"Posting to Snapchat.","type":"object","properties":{"enabled":{"description":"Post every video to Snapchat.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false}},"additionalProperties":false},"watermarkType":{"description":"Watermark: Your text or picture on the video. Every plan.\nChoices:\n- none — None: No watermark.\n- text — Text: watermarkText.\n- image — Picture: watermarkMediaId.\nDefault: none.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"Text: The words. Default: No text (leave it out).","type":"string","minLength":1,"maxLength":50},"watermarkTextColor":{"description":"Text colour: #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundColor":{"description":"Box colour: #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundOpacity":{"description":"Box: Box, 0 (none) to 1. From 0 to 1, in steps of 0.01. Default: 0.5.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"watermarkMediaId":{"description":"A picture from autoclips_media, by id. Default: No picture (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"watermarkImageOpacity":{"description":"Picture opacity: 0.3 to 1. From 0.3 to 1, in steps of 0.01. Default: 0.7.","type":"number","minimum":0.3,"maximum":1,"multipleOf":0.01},"watermarkVerticalPosition":{"description":"Height: Percent from the top. From 10 to 90 percent. Default: 85.","type":"integer","minimum":10,"maximum":90},"watermarkHorizontalPosition":{"description":"Across: Percent from the left. From 5 to 95 percent. Default: 85.","type":"integer","minimum":5,"maximum":95},"watermarkScale":{"description":"Size: 1 is normal. From 0.5 to 3, in steps of 0.01. Default: 1.","type":"number","minimum":0.5,"maximum":3,"multipleOf":0.01},"watermarkStartSeconds":{"description":"From: Seconds into the video it appears. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"watermarkEndSeconds":{"description":"Until: Seconds into the video it goes; 0 = to the end. At least 0.5 s after the start. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"outroId":{"description":"Outro: An end card from autoclips_outros, after the last scene. Paid plans (free: plan_required). \"none\" = no outro. A Story's own end card still closes the story; the outro plays after it. Default: No outro (leave it out).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"spendLimitPerDay":{"description":"The most it may spend a day, in credits (1 to 100,000). Left out: one day of runs at their most.","type":"integer","minimum":1,"maximum":100000},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["name","schedule"],"additionalProperties":false},"example":{"name":"Midnight Stories","schedule":{"timezone":"America/New_York","videosPerDay":1,"times":["18:00"]},"series":{"flavor":"you-decide","partsPerSeries":5,"direction":"Keep it creepy.","video":{"artStyle":"horror"}},"publishing":{"tiktok":{"enabled":true}}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"video":{"description":"An Explainer or Skit automation's video.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"series":{"description":"A Story series automation's settings.","type":"object","properties":{"flavor":{"type":"string","enum":["you-decide","true-story"]},"premiseSource":{"type":"string","enum":["ideas","custom"]},"premises":{"type":"array","items":{"type":"string"}},"partsPerSeries":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"afterLastPart":{"type":"string","enum":["new_series","stop"]},"minVoteHours":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"minVotes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"tieBreak":{"type":"string","enum":["coin","a","b"]},"direction":{"anyOf":[{"type":"string"},{"type":"null"}]},"castCharacterIds":{"type":"array","items":{"type":"string"}},"video":{"type":"object","properties":{"lengthSeconds":{"type":"string"},"motion":{"type":"string","enum":["stills","key","full"]},"voiceId":{"type":"string"},"pace":{"type":"string"},"language":{"type":"string"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}]},"captions":{"type":"boolean"},"captionStyle":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"cards":{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},"videoSpeed":{"type":"number"},"artStyle":{"type":"string"},"motionModel":{"description":"The AutoClips model the moving parts film with.","type":"string"},"music":{"type":"object","properties":{"mode":{"type":"string","enum":["bed","library","off"]},"trackId":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["mode","trackId","category"],"additionalProperties":false},"aspect":{"type":"string","const":"9:16"}},"required":["lengthSeconds","motion","voiceId","pace","language","locale","captions","captionStyle","cards","videoSpeed","artStyle","motionModel","music","aspect"],"additionalProperties":false}},"required":["flavor","premiseSource","premises","partsPerSeries","afterLastPart","minVoteHours","minVotes","tieBreak","direction","castCharacterIds","video"],"additionalProperties":false},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"seriesState":{"description":"Where the series is: its number, the last part posted, whether it waits for votes, the last vote.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"watermarkType":{"description":"none, text or image.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"A text watermark's words, or null.","anyOf":[{"type":"string"},{"type":"null"}]},"watermarkTextColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundOpacity":{"description":"0 to 1","type":"number"},"watermarkImageOpacity":{"description":"0.3 to 1","type":"number"},"watermarkVerticalPosition":{"description":"Percent from the top.","type":"number"},"watermarkHorizontalPosition":{"description":"Percent from the left.","type":"number"},"watermarkScale":{"description":"1 is normal.","type":"number"},"watermarkStartSeconds":{"description":"Seconds.","type":"number"},"watermarkEndSeconds":{"description":"Seconds; 0 = to the end.","type":"number"},"outroId":{"description":"Or null.","anyOf":[{"type":"string"},{"type":"null"}]},"partInProgress":{"type":"boolean"},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","status","pauseReason","schedule","topics","publishing","partInProgress","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"approvedCreditsPerDay":{"description":"The daily spending limit you approved.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"warnings":{"description":"Things to tell the user (for example that no posting account can be read for votes).","type":"array","items":{"type":"string"}}},"required":["automation","approvedCreditsPerDay","warnings"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d","name":"Midnight Stories","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["18:00"],"videosPerDay":1},"series":{"flavor":"you-decide","premiseSource":"ideas","premises":[],"partsPerSeries":5,"afterLastPart":"new_series","minVoteHours":6,"minVotes":1,"tieBreak":"coin","direction":"Keep it funny.","castCharacterIds":[],"video":{"lengthSeconds":"90","motion":"stills","voiceId":"nPczCjzI2devNBz1zQrb","pace":"brisk","language":"en","locale":null,"captions":true,"captionStyle":null,"cards":{"enabled":true,"theme":null},"videoSpeed":1,"artStyle":"horror","motionModel":"autoclips1","music":{"mode":"bed","trackId":null,"category":null},"aspect":"9:16"}},"topics":{"mode":"category","category":"weird","customTopic":null,"goal":"entertain","goalText":null,"cta":"none","ctaText":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":true,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"seriesState":null,"partInProgress":false,"spendLimit":{"creditsPerDay":2750,"approvedAt":"2026-10-25T09:00:00.000Z"},"estimatedCreditsPerRun":1550,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-10-25T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-10-25T09:00:00.000Z","updatedAt":"2026-10-25T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"},"approvedCreditsPerDay":2750,"warnings":[]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/automations/{automationId}":{"get":{"operationId":"stickman_automations_get","summary":"Read one Stickman automation: its settings, schedule, series state and recent runs.","description":"One Stickman automation: its settings, schedule, posting, daily spending limit and stats; for a Story series, where the series is (its number, the last part posted, whether it waits for votes, the last vote) and whether a part is being made now; and its last 10 runs.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.automations.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_automations action=get","parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation (automationId from stickman_automations list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation (automationId from stickman_automations list).","example":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"video":{"description":"An Explainer or Skit automation's video.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"series":{"description":"A Story series automation's settings.","type":"object","properties":{"flavor":{"type":"string","enum":["you-decide","true-story"]},"premiseSource":{"type":"string","enum":["ideas","custom"]},"premises":{"type":"array","items":{"type":"string"}},"partsPerSeries":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"afterLastPart":{"type":"string","enum":["new_series","stop"]},"minVoteHours":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"minVotes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"tieBreak":{"type":"string","enum":["coin","a","b"]},"direction":{"anyOf":[{"type":"string"},{"type":"null"}]},"castCharacterIds":{"type":"array","items":{"type":"string"}},"video":{"type":"object","properties":{"lengthSeconds":{"type":"string"},"motion":{"type":"string","enum":["stills","key","full"]},"voiceId":{"type":"string"},"pace":{"type":"string"},"language":{"type":"string"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}]},"captions":{"type":"boolean"},"captionStyle":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"cards":{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},"videoSpeed":{"type":"number"},"artStyle":{"type":"string"},"motionModel":{"description":"The AutoClips model the moving parts film with.","type":"string"},"music":{"type":"object","properties":{"mode":{"type":"string","enum":["bed","library","off"]},"trackId":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["mode","trackId","category"],"additionalProperties":false},"aspect":{"type":"string","const":"9:16"}},"required":["lengthSeconds","motion","voiceId","pace","language","locale","captions","captionStyle","cards","videoSpeed","artStyle","motionModel","music","aspect"],"additionalProperties":false}},"required":["flavor","premiseSource","premises","partsPerSeries","afterLastPart","minVoteHours","minVotes","tieBreak","direction","castCharacterIds","video"],"additionalProperties":false},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"seriesState":{"description":"Where the series is: its number, the last part posted, whether it waits for votes, the last vote.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"watermarkType":{"description":"none, text or image.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"A text watermark's words, or null.","anyOf":[{"type":"string"},{"type":"null"}]},"watermarkTextColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundOpacity":{"description":"0 to 1","type":"number"},"watermarkImageOpacity":{"description":"0.3 to 1","type":"number"},"watermarkVerticalPosition":{"description":"Percent from the top.","type":"number"},"watermarkHorizontalPosition":{"description":"Percent from the left.","type":"number"},"watermarkScale":{"description":"1 is normal.","type":"number"},"watermarkStartSeconds":{"description":"Seconds.","type":"number"},"watermarkEndSeconds":{"description":"Seconds; 0 = to the end.","type":"number"},"outroId":{"description":"Or null.","anyOf":[{"type":"string"},{"type":"null"}]},"partInProgress":{"type":"boolean"},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","status","pauseReason","schedule","topics","publishing","partInProgress","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"recentRuns":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"testRun":{"type":"boolean"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsUsed":{"type":"number"},"posts":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"published":{"type":"boolean"},"link":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["published","link"],"additionalProperties":false}},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","testRun","topic","projectId","videoUrl","creditsUsed","posts","error","startedAt","completedAt"],"additionalProperties":false}},"warnings":{"description":"Things to tell the user (for example that no posting account can be read for votes).","type":"array","items":{"type":"string"}}},"required":["automation","recentRuns","warnings"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"automation":{"id":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d","name":"Midnight Stories","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["18:00"],"videosPerDay":1},"series":{"flavor":"you-decide","premiseSource":"ideas","premises":[],"partsPerSeries":5,"afterLastPart":"new_series","minVoteHours":6,"minVotes":1,"tieBreak":"coin","direction":"Keep it funny.","castCharacterIds":[],"video":{"lengthSeconds":"90","motion":"stills","voiceId":"nPczCjzI2devNBz1zQrb","pace":"brisk","language":"en","locale":null,"captions":true,"captionStyle":null,"cards":{"enabled":true,"theme":null},"videoSpeed":1,"artStyle":"horror","motionModel":"autoclips1","music":{"mode":"bed","trackId":null,"category":null},"aspect":"9:16"}},"topics":{"mode":"category","category":"weird","customTopic":null,"goal":"entertain","goalText":null,"cta":"none","ctaText":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":true,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"seriesState":null,"partInProgress":false,"spendLimit":{"creditsPerDay":2750,"approvedAt":"2026-10-25T09:00:00.000Z"},"estimatedCreditsPerRun":1550,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-10-25T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-10-25T09:00:00.000Z","updatedAt":"2026-10-25T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"},"recentRuns":[{"id":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","status":"completed","testRun":false,"topic":"Story series - Part 2","projectId":"c4a2d3e5-6f70-4b8c-9dae-1f2a3b4c5d6e","videoUrl":"https://media.autoclips.app/stickman/part-2.mp4","creditsUsed":1490,"posts":{"tiktok":{"published":true,"link":"https://www.tiktok.com/@you/video/1"}},"error":null,"startedAt":"2026-10-25T09:00:00.000Z","completedAt":"2026-10-25T09:24:00.000Z"}],"warnings":[]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"stickman_automations_update","summary":"Change an automation's name, schedule, video or series settings, topics, posting, watermark or outro.","description":"Changes the parts of a Stickman automation you send; everything else stays. The watermark (only the watermark fields you send change) and the outro (outroId; \"none\" takes it off) apply to every video it makes from then on. A Story series stays a series and an Explainer or Skit automation stays one (409 series_mode_locked otherwise). Series changes to the story kind, ideas, cast, narrator and language start with the next series; length, motion, captions, music, direction, parts and vote rules apply from the next part. A change of topic, angle, mode or language writes new ideas (it counts toward the free-AI daily limit). A change that would raise the daily spend above the automation's daily limit, or any raise when it has none, is refused: set the limit first with set_spend_limit (409 spend_limit_needed). Switching posting on, adding a platform, changing the account a platform posts with or making YouTube videos more public (private to unlisted or public) needs the publish permission, and AI apps ask first.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.automations.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_automations action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The automation's name: unique on your account, at most 100 characters.","type":"string","minLength":1,"maxLength":100},"schedule":{"description":"When it runs. A new automation needs all three; an update changes only what you send.","type":"object","properties":{"timezone":{"description":"The time zone of the posting times (IANA, for example \"America/New_York\").","type":"string","minLength":1,"maxLength":64},"videosPerDay":{"description":"Videos a day, 1 to 3: one per posting time.","type":"integer","minimum":1,"maximum":3},"times":{"description":"The posting times, one per video a day (\"09:00\", 24-hour).","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}}},"additionalProperties":false},"video":{"description":"The video of an Explainer or Skit automation (not with series). Full motion uses AutoClips clips.","type":"object","properties":{"mode":{"description":"Kind of video: An Explainer or a Skit. Stories start with stickman.story.quick_start or a plan instead.\nChoices:\n- explainer — Explainer: A deadpan narrator walks through an absurd scheme or dark listicle, 30 to 90 seconds.\n- skit — Skit: A ten-second animated gag built on silence, timing and one perfect punchline.\nDefault: explainer.","type":"string","enum":["explainer","skit"]},"angle":{"description":"Angle: The kind of joke the script is built on. Each angle belongs to a mode (meta.modes) and comes with example topics (meta.exampleChips, by mode); Custom takes your own topic in either mode.\nChoices:\n- unethical-money — Unethical Money: An absurd money scheme narrated like a business plan, part N of an endless series.\n- dark-hacks — Dark Hacks: A life-hack listicle where every tip is absurd and the delivery never blinks.\n- psychology — Dark Psychology: The manipulation tricks used on you every day, decoded one by one.\n- tech — Tech & AI: What the machine in your pocket is really doing, briefed like a leak.\n- survival — Dark Survival: Field-manual survival rules that drift from plausible to unhinged.\n- history — Dark History: The hidden, sinister story behind an everyday thing, read like a classified file.\n- custom — Custom: Your own topic, poured into the deadpan explainer grammar. In a Skit: your own premise, run through the skit timing machine.\n- relatable-fear — Relatable Fear: An everyday nighttime fear staged for a jump-laugh.\n- good-bad-news — Good News, Bad News: A two-character dialogue joke where the bad news is the punchline.\n- gaming — Gaming: One last game, and the passage of time that follows.\n- dev-life — Dev Life: The ten-second tragedy of shipping software, staged at one desk.\n- melancholy — Melancholy: A wordless, cinematic sad moment that lands in the chest.\nDefault: Unethical Money for an Explainer, Relatable Fear for a Skit (leave it out).","type":"string","enum":["unethical-money","dark-hacks","psychology","tech","survival","history","custom","relatable-fear","good-bad-news","gaming","dev-life","melancholy"]},"angleRotation":{"description":"fixed keeps the angle; rotate picks a new one each run.","type":"string","enum":["fixed","rotate"]},"lengthSeconds":{"description":"Automation video length: How long each video of an Explainer or Skit automation runs. A Story series automation takes storyLength instead.\nChoices:\n- 30 — 30 seconds: A 30-second video each run. (600 credits base a video (x your plan multiplier))\n- 60 — 1 minute: A 60-second video each run. (1100 credits base a video (x your plan multiplier))\n- 70 — 1.2 minutes: A 70-second video each run. (1250 credits base a video (x your plan multiplier))\nDefault: 60.","type":"string","enum":["30","60","70"]},"motion":{"description":"Explainer motion: How much of an Explainer moves. Leaving it out gives Classic; the website starts a new video on Full Motion. Moving clips are priced by the clip model.\nChoices:\n- classic — Classic: Cinematic zooms sweep across every scene.\n- enhanced — Enhanced: Key scenes come alive with real motion. (Adds 2 clips, each priced by the clip model)\n- full — Full Motion: Every single scene is animated with real motion. (Adds one clip a scene (7 to 18 scenes by length), each priced by the clip model)\nDefault: classic.","type":"string","enum":["classic","enhanced","full"]},"clipModel":{"description":"Clip model: Which model makes an Explainer's moving clips (Enhanced and Full Motion). A clip AutoClips 1 cannot make is made by a backup model, billed at the backup's price.\nChoices:\n- autoclips1 — AutoClips 1: Our main model, 768p. Each clip runs as long as its scene. (Billed by the second, 15 credits a second (5 to 15 seconds a clip): from 80 a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- autoclips1Upscaled — AutoClips 1 1080p Upscaled: AutoClips 1, sharpened to 1080p. (Billed by the second, 20 credits a second (5 to 15 seconds a clip): from 107 a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- autoclips1Light — AutoClips 1 Lite: Half the price, 720p. (Billed by the second, 8 credits a second (5 to 15 seconds a clip): from 43 a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- autoclips1LightHd — AutoClips 1 Lite Full HD: AutoClips 1 Lite drawn at full 1080p. (Billed by the second, 23 credits a second (5 to 15 seconds a clip): from 118 a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- omniMax — Pro Max: Flat price per clip. (805 credits a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- kling3 — Pro: Handles darker scenes. (805 credits a clip (x your plan multiplier), its planning included)\n- autoclips — AutoClips 1 (old name): The old name of autoclips1, still taken. Send autoclips1 instead. (As AutoClips 1)\nDefault: autoclips1.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd","omniMax","kling3","autoclips"]},"voiceId":{"description":"Narrator (Explainer): Who reads an Explainer. meta.sampleUrl plays the same line in each voice.\nChoices:\n- nPczCjzI2devNBz1zQrb — Brian: Deep, relentless deadpan — the signature stickman read.\n- JBFqnCBsd6RMkjVDRZzb — George: British documentary storyteller, brisk and crisp.\n- EXAVITQu4vr4xnSDxMaL — Sarah: Confident, matter-of-fact professional.\n- pNInz6obpgDQGcFmaJgB — Adam: Deep and dominant — cuts through the feed instantly.\n- TxGEqnHWrfWFTfGW9XjX — Josh: Clear, engaging classic narrator.\n- onwK4e9ZLuTAKqWW03F9 — Daniel: Calm broadcast narrator, most measured read.\nDefault: nPczCjzI2devNBz1zQrb.","type":"string","enum":["nPczCjzI2devNBz1zQrb","JBFqnCBsd6RMkjVDRZzb","EXAVITQu4vr4xnSDxMaL","pNInz6obpgDQGcFmaJgB","TxGEqnHWrfWFTfGW9XjX","onwK4e9ZLuTAKqWW03F9"]},"pace":{"description":"Reading pace: How fast the narrator reads. A faster pace fits more words into the same length.\nChoices:\n- relaxed — Relaxed: Everyday speaking pace — easiest to follow.\n- natural — Natural: Steady documentary read.\n- brisk — Brisk: Fast and punchy, still every word clear.\n- rapid — Rapid: Breathless, relentless — the hardest read to follow.\nDefault: brisk.","type":"string","enum":["relaxed","natural","brisk","rapid"]},"skitModel":{"description":"Skit quality: Which quality tier makes a Skit's clips. A Skit has one to four clips; the joke decides how many.\nChoices:\n- omniMax — Pro Max: 8-second clips, the best quality and the fastest to make. (800 credits a clip (x your plan multiplier); a clip it cannot make is made by Pro at 1000)\n- kling3 — Pro: 10-second clips with the most cinematic motion. (1000 credits a clip (x your plan multiplier))\n- veo31lite — Lite: Quick and affordable 8-second clips. (500 credits a clip (x your plan multiplier))\nDefault: omniMax.","type":"string","enum":["omniMax","kling3","veo31lite"]},"language":{"description":"The spoken language code (stickman.capabilities.get lists what each kind of video speaks right now).","type":"string","minLength":2,"maxLength":16},"music":{"description":"The background music.","type":"object","properties":{"mode":{"description":"none, or library: a track or a mood of the music library.","type":"string","enum":["none","library"]},"category":{"description":"A mood of the music library: popular, playful, sneaky, mysterious, epic, chill, upbeat, whimsical, v3-animals, v3-crime, v3-general, v3-history, v3-horror, v3-science, v3-space.","type":"string","enum":["popular","playful","sneaky","mysterious","epic","chill","upbeat","whimsical","v3-animals","v3-crime","v3-general","v3-history","v3-horror","v3-science","v3-space"]},"trackId":{"title":"Music (Stickman videos (Explainer, Skit, Story) option musicTrack)","description":"Music: A music track by id: \"none\" (no music, when an Explainer or Skit is made; a render refuses it, since a render always keeps the video's music: turn a Story's music off with the edit music.none), a track of the music library, or a Story music bed (meta.kind \"bed\"). Links are never taken: the id picks the track.\nChoices: one of 232 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=musicTrack) to see them all.\nDefault: The format's default (Story: the series bed) (leave it out).","type":"string"}},"required":["mode"],"additionalProperties":false},"musicVolumeDb":{"description":"The music's volume under the voice, -30 to 0 dB.","type":"integer","minimum":-30,"maximum":0}},"additionalProperties":false},"topics":{"description":"Where the ideas come from. For a Story series, the theme of new story ideas.","type":"object","properties":{"mode":{"description":"category: ideas on a topic category; custom: ideas on your own theme.","type":"string","enum":["category","custom"]},"category":{"description":"Topic: The theme an automation's ideas are written from.\nChoices:\n- history — History & Ancient Mysteries: Ancient civilizations, historical events, mysteries from the past.\n- science — Science & Nature: Scientific discoveries, natural phenomena, how things work.\n- horror — Horror & Dark Facts: Creepy stories, dark history, unsettling facts.\n- psychology — Psychology & Mind: Human behavior, cognitive science, mental health.\n- tech — Technology & Future: AI, gadgets, future tech, digital world.\n- nature — Animals & Wildlife: Animal facts, wildlife, evolution, ecosystems.\n- money — Money & Finance: Wealth, economics, investing, financial history.\n- health — Health & Body: Human body, nutrition, fitness, medical facts.\n- weird — Weird & Unusual: Strange facts, bizarre stories, oddities.\n- crime — Crime & Mystery: True crime, mysteries, forensics, detective stories.\n- space — Space & Cosmos: Astronomy, space exploration, cosmic mysteries.\n- food — Food & Cooking: Culinary science, food history, cooking facts.\nDefault: weird.","type":"string","enum":["history","science","horror","psychology","tech","nature","money","health","weird","crime","space","food"]},"customTopic":{"description":"Your own theme for new ideas (at most 2,000 characters).","type":"string","minLength":1,"maxLength":2000},"goal":{"description":"Goal: What an automation's videos are written to achieve.\nChoices:\n- entertain — Entertain: This format's default objective.\n- views — Get Views: Maximize video views and reach.\n- followers — Grow Followers: Build audience and follower count.\n- sales — Drive Sales: Promote product/service and drive conversions.\n- awareness — Brand Awareness: Increase brand recognition and visibility.\n- custom — Custom Goal: Define your own goal and strategy.\nDefault: entertain.","type":"string","enum":["entertain","views","followers","sales","awareness","custom"]},"goalText":{"description":"Your own goal, in words (at most 500 characters).","type":"string","minLength":1,"maxLength":500},"cta":{"description":"Call to action: What an automation's videos ask viewers to do at the end.\nChoices:\n- none — No call to action: Let the video end on its own.\n- follow — Follow for More: Ask viewers to follow for similar content.\n- subscribe — Subscribe: Ask viewers to subscribe for more content.\n- share — Share This: Ask viewers to share the video.\n- custom — Custom CTA: Write your own call-to-action.\nDefault: none.","type":"string","enum":["none","follow","subscribe","share","custom"]},"ctaText":{"description":"Your own call to action (at most 200 characters).","type":"string","minLength":1,"maxLength":200}},"additionalProperties":false},"series":{"description":"A Story series automation (instead of video): each run makes the next part of the series. A new series needs flavor.","type":"object","properties":{"flavor":{"description":"you-decide: each part ends on a vote the comments decide; true-story: a real story told chapter by chapter.","type":"string","enum":["you-decide","true-story"]},"premiseSource":{"description":"Where each story comes from: How an automated Story series finds the idea of each new series.\nChoices:\n- ideas — Fresh ideas: New story ideas are written from the topic you pick.\n- custom — Your ideas: Your own story ideas (1 to 10), used in turn.\nDefault: ideas.","type":"string","enum":["ideas","custom"]},"premises":{"description":"Your own story ideas, 10 to 2,000 characters each (at most 10): one per series, in turn.","maxItems":10,"type":"array","items":{"type":"string","minLength":10,"maxLength":2000}},"partsPerSeries":{"description":"Parts per series: How many parts an automated Story series makes before it ends. Each part is one video run. From 2 to 20 parts. Default: 5.","type":"integer","minimum":2,"maximum":20},"afterLastPart":{"description":"After the last part: What an automated Story series does when its last part is posted.\nChoices:\n- new_series — Start a new series: The next run starts Part 1 of a new story.\n- stop — Stop: The automation pauses; resuming it starts a new series.\nDefault: new_series.","type":"string","enum":["new_series","stop"]},"minVoteHours":{"description":"Hours to vote: You Decide series: how long viewers have to vote in the comments before the next part is made. Kept, but unused, for True Story (no vote). From 1 to 48 hours. Default: 6.","type":"integer","minimum":1,"maximum":48},"minVotes":{"description":"Votes needed: You Decide series: the fewest comment votes that decide the next part. With fewer, the tie rule decides. From 1 to 1000 votes. Default: 1.","type":"integer","minimum":1,"maximum":1000},"tieBreak":{"description":"Tie rule: You Decide series: which way the story goes on a tie, or when too few votes came in.\nChoices:\n- coin — Coin toss: A fair coin toss, the same answer every time for the same part.\n- a — Choice A: The first choice of the vote.\n- b — Choice B: The second choice of the vote.\nDefault: coin.","type":"string","enum":["coin","a","b"]},"direction":{"description":"How every part should go, in a sentence (at most 300 characters); null clears it.","anyOf":[{"type":"string","minLength":1,"maxLength":300},{"type":"null"}]},"castCharacterIds":{"description":"Up to 4 of your cast (characterId from stickman_cast list, or a preset) who star in every part.","maxItems":4,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"video":{"description":"Each part's video. Every part is vertical (9:16).","type":"object","properties":{"lengthSeconds":{"description":"Story length: How long a Story (or a Story part) runs. It sets the base price; moving scenes are added on top.\nChoices:\n- 30 — 30 seconds: A 30-second story. (600 credits base (x your plan multiplier))\n- 40 — 40 seconds: A 40-second story. (750 credits base (x your plan multiplier))\n- 50 — 50 seconds: A 50-second story. (950 credits base (x your plan multiplier))\n- 60 — 1 minute: A 60-second story. (1100 credits base (x your plan multiplier))\n- 70 — 1.2 minutes: A 70-second story. (1250 credits base (x your plan multiplier))\n- 80 — 1.3 minutes: A 80-second story. (1400 credits base (x your plan multiplier))\n- 90 — 1.5 minutes: A 90-second story. (1550 credits base (x your plan multiplier))\n- 100 — 1.7 minutes: A 100-second story. (1700 credits base (x your plan multiplier))\n- 110 — 1.8 minutes: A 110-second story. (1850 credits base (x your plan multiplier))\n- 120 — 2 minutes: A 120-second story. (2000 credits base (x your plan multiplier))\nDefault: 90.","type":"string","enum":["30","40","50","60","70","80","90","100","110","120"]},"motion":{"description":"Story motion: How much of a Story moves. Moving scenes are paid plans only and are charged as each one is made, never above the quote's \"at most\". Story options (You Decide, True Story) need Stickman Story switched on for the account; stickman.capabilities.get says what is on right now.\nChoices:\n- stills — Stills: Pictures with camera moves; nothing is animated.\n- key — Key moments: The key moments of the story move. (118 credits a moving scene (a 5-second clip on AutoClips 1; storyMotionModel changes it), at most the quote's cap; plans: paid)\n- full — Full motion: Every picture scene moves. (118 credits a moving scene (a 5-second clip on AutoClips 1; storyMotionModel changes it), at most the quote's cap; plans: paid)\nDefault: stills.","type":"string","enum":["stills","key","full"]},"voiceId":{"description":"Narrator (Story): Who reads a Story. The last 14 (meta.v2Only) need the 20-voice switch; stickman.capabilities.get lists what is offered now. meta.sampleUrl plays a sample.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=storyVoice) to see them all.\nDefault: nPczCjzI2devNBz1zQrb.","type":"string","enum":["nPczCjzI2devNBz1zQrb","JBFqnCBsd6RMkjVDRZzb","EXAVITQu4vr4xnSDxMaL","pNInz6obpgDQGcFmaJgB","TxGEqnHWrfWFTfGW9XjX","onwK4e9ZLuTAKqWW03F9","N2lVS1w4EtoT3dr4eOWO","cjVigY5qzO86Huf0OWal","pqHfZKP75CvOlQylNhV4","iP95p4xoKVk53GoZ742B","TX3LPaxmHKxFdv7VOQHJ","IKne3meq5aSn9XLyUdCD","CwhRBWXzGAHq8TQ4Fs17","pFZP5JQG7iQjIQuC4Bku","Xb7hH8MSUJpSbSDYk0k2","9BWtsMINqrJLrRacOk9x","XrExE9yKIg1WjnnlVkGX","cgSgspJ2msm6clMCkdW9","FGY2WhTYpPnrIDTdsKH5","XB0fDUnXU5powFXDhCwa"]},"pace":{"description":"Reading pace: How fast the narrator reads. A faster pace fits more words into the same length.\nChoices:\n- relaxed — Relaxed: Everyday speaking pace — easiest to follow.\n- natural — Natural: Steady documentary read.\n- brisk — Brisk: Fast and punchy, still every word clear.\n- rapid — Rapid: Breathless, relentless — the hardest read to follow.\nDefault: brisk.","type":"string","enum":["relaxed","natural","brisk","rapid"]},"language":{"title":"Language (Story) (Stickman videos (Explainer, Skit, Story) option storyLanguage)","description":"Language (Story): The language of a Story's narration, cards and captions. Some languages are switched on later than others: a language that is not offered yet is refused with language_not_offered, and stickman.capabilities.get lists what is offered now.\nChoices: one of 94 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=storyLanguage) to see them all.\nDefault: en.","type":"string"},"locale":{"description":"Language variant: Which variant of a Story language to use, for the languages that have one (meta.language). Leave it out for the language's usual variant.\nChoices:\n- es-419 — Spanish (Latin America): Spanish as spoken in Latin America.\n- es-ES — Spanish (Spain): Spanish as spoken in Spain.\n- es-MX — Spanish (Mexico): Spanish as spoken in Mexico.\n- pt-BR — Portuguese (Brazil): Portuguese as spoken in Brazil.\n- pt-PT — Portuguese (Portugal): Portuguese as spoken in Portugal.\n- bn-BD — Bengali (Bangladesh): Bengali as spoken in Bangladesh.\n- bn-IN — Bengali (India): Bengali as spoken in India.\nDefault: The language's usual variant (leave it out).","type":"string","enum":["es-419","es-ES","es-MX","pt-BR","pt-PT","bn-BD","bn-IN"]},"captions":{"description":"Captions on or off.","type":"boolean"},"captionStyle":{"anyOf":[{"description":"The caption look. Leave a key out to keep the format's own.","type":"object","properties":{"highlightStyle":{"description":"Caption look: How the spoken words appear on screen (captionStyle.highlightStyle). The same looks every AutoClips format uses.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionStyle) to see them all.\nDefault: The format's own look (leave it out).","type":"string","enum":["classic","color-only","scale-up","typewriter","progressive","karaoke","bounce","outline","background","shadow-pop","pop-color","neon","underline","gradient","boxed","glow"]},"fontFamily":{"description":"Caption font: The lettering of the captions (captionStyle.fontFamily).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionFont) to see them all.\nDefault: The caption look's own font (leave it out).","type":"string","enum":["Montserrat","BebasNeue","Anton","LeagueSpartan"]},"position":{"description":"Caption position: Where the captions sit (captionStyle.position).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionPosition) to see them all.\nDefault: The format's own position (leave it out).","type":"string","enum":["top","upper-third","center","lower-third","bottom"]},"positionY":{"description":"Where the captions sit, 0 (top) to 100 (bottom); wins over position.","type":"number","minimum":0,"maximum":100},"groupSize":{"description":"Words at a time: How many words the captions show at once (captionStyle.groupSize, sent as a number).\nChoices:\n- 2 — 2 words: Punchy. Reads fastest.\n- 3 — 3 words: The default.\n- 4 — 4 words: Calmer, fewer changes.\nDefault: The caption look's own size (leave it out).","type":"string","enum":["2","3","4"]},"fontSize":{"description":"Caption size, 28 to 110.","type":"integer","minimum":28,"maximum":110},"color":{"description":"Caption colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"highlightColor":{"description":"The spoken word's colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"showBackground":{"description":"A box behind the captions.","type":"boolean"},"backgroundOpacity":{"description":"How solid that box is, 0 to 1.","type":"number","minimum":0,"maximum":1}},"additionalProperties":false},{"type":"null"}]},"cards":{"description":"The on-screen text cards.","type":"object","properties":{"enabled":{"description":"On-screen text cards on or off.","type":"boolean"},"theme":{"anyOf":[{"description":"Text card look: The look of a Story's on-screen text cards and its end card.\nChoices:\n- night — Night: Dark card, green edge.\n- ink — Ink: Dark tiles, pink accents, paper fact cards.\n- clean — Clean: White card, black text.\nDefault: Night for You Decide, Ink for True Story (leave it out).","type":"string","enum":["night","ink","clean"]},{"type":"null"}]}},"additionalProperties":false},"videoSpeed":{"description":"Video speed: How fast the finished video plays, from 1x to 3x in steps of 0.1. The page's quick picks: 1x, 1.1x, 1.2x, 1.3x, 1.5x, 2x, 3x. Free: it changes no price. From 1 to 3 x, in steps of 0.1. Default: 1.","type":"number","minimum":1,"maximum":3,"multipleOf":0.1},"artStyle":{"description":"Art style: The look of the pictures in a Story: the places, the light and the colours. The stick figures stay the same in every style. A next part keeps the style of the part before it. meta.exampleUrl shows the same scene in each style.\nChoices:\n- default — Cinematic: Painted night scenes in teal and warm orange. The classic look. Best for any story.\n- horror — Horror Glow: Dark and creepy, lit by vivid green, red and purple light. Best for scary, survival and mystery stories.\n- noir — Rainy Noir: Rain-soaked streets, hard shadows and cold blue light. Crime and secrets. Best for crime, heists and true stories.\n- sunny — Bright Day: Sunny, colourful and cheerful, like a Saturday-morning cartoon. Best for funny, feel-good and kids stories.\n- epic — Golden Epic: Huge skies, golden sunsets and dust in the air. Feels like a movie. Best for history, war and adventure.\nDefault: default.","type":"string","enum":["default","horror","noir","sunny","epic"]},"motionModel":{"description":"The AutoClips model the moving parts are filmed with (default autoclips1). Only with key or full motion; characters who speak film on AutoClips 1 when a Lite model is picked.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd"]},"music":{"description":"The parts' music: the Story music bed, a library track or mood, or none.","type":"object","properties":{"mode":{"description":"Series music: The music of every part of an automated Story series.\nChoices:\n- bed — Story music: The music bed made for the story kind.\n- library — From the library: A track or a mood of the music library (15 moods).\n- off — No music: The parts have no music.\nDefault: bed.","type":"string","enum":["bed","library","off"]},"trackId":{"anyOf":[{"title":"Music (Stickman videos (Explainer, Skit, Story) option musicTrack)","description":"Music: A music track by id: \"none\" (no music, when an Explainer or Skit is made; a render refuses it, since a render always keeps the video's music: turn a Story's music off with the edit music.none), a track of the music library, or a Story music bed (meta.kind \"bed\"). Links are never taken: the id picks the track.\nChoices: one of 232 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=musicTrack) to see them all.\nDefault: The format's default (Story: the series bed) (leave it out).","type":"string"},{"type":"null"}]},"category":{"anyOf":[{"description":"A mood of the music library: popular, playful, sneaky, mysterious, epic, chill, upbeat, whimsical, v3-animals, v3-crime, v3-general, v3-history, v3-horror, v3-science, v3-space.","type":"string","enum":["popular","playful","sneaky","mysterious","epic","chill","upbeat","whimsical","v3-animals","v3-crime","v3-general","v3-history","v3-horror","v3-science","v3-space"]},{"type":"null"}]}},"required":["mode"],"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"publishing":{"description":"Where each video goes. Switching posting on, changing the posting account or making YouTube videos more public needs the publish permission; only the platforms you send change.","type":"object","properties":{"email":{"description":"Email you when each video is ready.","type":"boolean"},"library":{"description":"Keep each video in My Videos.","type":"boolean"},"tiktok":{"description":"Posting to TikTok.","type":"object","properties":{"enabled":{"description":"Post every video to TikTok.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"youtube":{"description":"Posting to YouTube.","type":"object","properties":{"enabled":{"description":"Post every video to YouTube.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"},"privacy":{"description":"public, unlisted or private (default private; private videos get no comments, so no votes).","type":"string","enum":["public","unlisted","private"]},"categoryId":{"description":"The YouTube category id (2 Autos & Vehicles, 23 Comedy, 27 Education, 24 Entertainment, 1 Film & Animation, 20 Gaming, 26 Howto & Style, 10 Music, 25 News & Politics, 29 Nonprofits & Activism, 22 People & Blogs, 15 Pets & Animals, 28 Science & Technology, 17 Sports, 19 Travel & Events).","type":"string","enum":["1","2","10","15","17","19","20","22","23","24","25","26","27","28","29"]},"useAIMetadata":{"description":"Write the title and description from the video (default true).","type":"boolean"}},"required":["enabled"],"additionalProperties":false},"instagram":{"description":"Posting to Instagram.","type":"object","properties":{"enabled":{"description":"Post every video to Instagram.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"facebook":{"description":"Posting to Facebook.","type":"object","properties":{"enabled":{"description":"Post every video to Facebook.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"twitter":{"description":"Posting to X.","type":"object","properties":{"enabled":{"description":"Post every video to X.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"snapchat":{"description":"Posting to Snapchat.","type":"object","properties":{"enabled":{"description":"Post every video to Snapchat.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false}},"additionalProperties":false},"watermarkType":{"description":"Watermark: Your text or picture on the video. Every plan.\nChoices:\n- none — None: No watermark.\n- text — Text: watermarkText.\n- image — Picture: watermarkMediaId.\nDefault: none.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"Text: The words. Default: No text (leave it out).","type":"string","minLength":1,"maxLength":50},"watermarkTextColor":{"description":"Text colour: #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundColor":{"description":"Box colour: #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundOpacity":{"description":"Box: Box, 0 (none) to 1. From 0 to 1, in steps of 0.01. Default: 0.5.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"watermarkMediaId":{"description":"A picture from autoclips_media, by id. Default: No picture (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"watermarkImageOpacity":{"description":"Picture opacity: 0.3 to 1. From 0.3 to 1, in steps of 0.01. Default: 0.7.","type":"number","minimum":0.3,"maximum":1,"multipleOf":0.01},"watermarkVerticalPosition":{"description":"Height: Percent from the top. From 10 to 90 percent. Default: 85.","type":"integer","minimum":10,"maximum":90},"watermarkHorizontalPosition":{"description":"Across: Percent from the left. From 5 to 95 percent. Default: 85.","type":"integer","minimum":5,"maximum":95},"watermarkScale":{"description":"Size: 1 is normal. From 0.5 to 3, in steps of 0.01. Default: 1.","type":"number","minimum":0.5,"maximum":3,"multipleOf":0.01},"watermarkStartSeconds":{"description":"From: Seconds into the video it appears. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"watermarkEndSeconds":{"description":"Until: Seconds into the video it goes; 0 = to the end. At least 0.5 s after the start. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"outroId":{"description":"Outro: An end card from autoclips_outros, after the last scene. Paid plans (free: plan_required). \"none\" = no outro. A Story's own end card still closes the story; the outro plays after it. Default: No outro (leave it out).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"additionalProperties":false},"example":{"series":{"video":{"lengthSeconds":"60","motion":"key"}}}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation (automationId from stickman_automations list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation (automationId from stickman_automations list).","example":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"video":{"description":"An Explainer or Skit automation's video.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"series":{"description":"A Story series automation's settings.","type":"object","properties":{"flavor":{"type":"string","enum":["you-decide","true-story"]},"premiseSource":{"type":"string","enum":["ideas","custom"]},"premises":{"type":"array","items":{"type":"string"}},"partsPerSeries":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"afterLastPart":{"type":"string","enum":["new_series","stop"]},"minVoteHours":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"minVotes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"tieBreak":{"type":"string","enum":["coin","a","b"]},"direction":{"anyOf":[{"type":"string"},{"type":"null"}]},"castCharacterIds":{"type":"array","items":{"type":"string"}},"video":{"type":"object","properties":{"lengthSeconds":{"type":"string"},"motion":{"type":"string","enum":["stills","key","full"]},"voiceId":{"type":"string"},"pace":{"type":"string"},"language":{"type":"string"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}]},"captions":{"type":"boolean"},"captionStyle":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"cards":{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},"videoSpeed":{"type":"number"},"artStyle":{"type":"string"},"motionModel":{"description":"The AutoClips model the moving parts film with.","type":"string"},"music":{"type":"object","properties":{"mode":{"type":"string","enum":["bed","library","off"]},"trackId":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["mode","trackId","category"],"additionalProperties":false},"aspect":{"type":"string","const":"9:16"}},"required":["lengthSeconds","motion","voiceId","pace","language","locale","captions","captionStyle","cards","videoSpeed","artStyle","motionModel","music","aspect"],"additionalProperties":false}},"required":["flavor","premiseSource","premises","partsPerSeries","afterLastPart","minVoteHours","minVotes","tieBreak","direction","castCharacterIds","video"],"additionalProperties":false},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"seriesState":{"description":"Where the series is: its number, the last part posted, whether it waits for votes, the last vote.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"watermarkType":{"description":"none, text or image.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"A text watermark's words, or null.","anyOf":[{"type":"string"},{"type":"null"}]},"watermarkTextColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundOpacity":{"description":"0 to 1","type":"number"},"watermarkImageOpacity":{"description":"0.3 to 1","type":"number"},"watermarkVerticalPosition":{"description":"Percent from the top.","type":"number"},"watermarkHorizontalPosition":{"description":"Percent from the left.","type":"number"},"watermarkScale":{"description":"1 is normal.","type":"number"},"watermarkStartSeconds":{"description":"Seconds.","type":"number"},"watermarkEndSeconds":{"description":"Seconds; 0 = to the end.","type":"number"},"outroId":{"description":"Or null.","anyOf":[{"type":"string"},{"type":"null"}]},"partInProgress":{"type":"boolean"},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","status","pauseReason","schedule","topics","publishing","partInProgress","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"ideasRewritten":{"description":"True when the change writes new ideas for the automation.","type":"boolean"},"warnings":{"description":"Things to tell the user (for example that no posting account can be read for votes).","type":"array","items":{"type":"string"}}},"required":["automation","ideasRewritten","warnings"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d","name":"Midnight Stories","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["18:00"],"videosPerDay":1},"series":{"flavor":"you-decide","premiseSource":"ideas","premises":[],"partsPerSeries":5,"afterLastPart":"new_series","minVoteHours":6,"minVotes":1,"tieBreak":"coin","direction":"Keep it funny.","castCharacterIds":[],"video":{"lengthSeconds":"60","motion":"key","voiceId":"nPczCjzI2devNBz1zQrb","pace":"brisk","language":"en","locale":null,"captions":true,"captionStyle":null,"cards":{"enabled":true,"theme":null},"videoSpeed":1,"artStyle":"horror","motionModel":"autoclips1","music":{"mode":"bed","trackId":null,"category":null},"aspect":"9:16"}},"topics":{"mode":"category","category":"weird","customTopic":null,"goal":"entertain","goalText":null,"cta":"none","ctaText":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":true,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"seriesState":null,"partInProgress":false,"spendLimit":{"creditsPerDay":2750,"approvedAt":"2026-10-25T09:00:00.000Z"},"estimatedCreditsPerRun":1550,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-10-25T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-10-25T09:00:00.000Z","updatedAt":"2026-10-25T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"},"ideasRewritten":false,"warnings":[]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"stickman_automations_delete","summary":"Delete an automation and its run history.","description":"Deletes the Stickman automation and its run history. The videos it made stay in My Videos. Refused while a run is being made (409 run_active: wait, or cancel_run) or a series part is being made (409 series_part_in_flight), so no run is left half-settled.\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"stickman.automations.delete","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_automations action=delete","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation (automationId from stickman_automations list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation (automationId from stickman_automations list).","example":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"deleted":true,"id":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/automations/{automationId}/pause":{"post":{"operationId":"stickman_automations_pause","summary":"Pause an automation; it makes nothing until it is resumed.","description":"Pauses a Stickman automation: it makes and posts nothing until it is resumed. A run already being made finishes. Pausing a paused automation changes nothing.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.automations.pause","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_automations action=pause","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation (automationId from stickman_automations list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation (automationId from stickman_automations list).","example":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"video":{"description":"An Explainer or Skit automation's video.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"series":{"description":"A Story series automation's settings.","type":"object","properties":{"flavor":{"type":"string","enum":["you-decide","true-story"]},"premiseSource":{"type":"string","enum":["ideas","custom"]},"premises":{"type":"array","items":{"type":"string"}},"partsPerSeries":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"afterLastPart":{"type":"string","enum":["new_series","stop"]},"minVoteHours":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"minVotes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"tieBreak":{"type":"string","enum":["coin","a","b"]},"direction":{"anyOf":[{"type":"string"},{"type":"null"}]},"castCharacterIds":{"type":"array","items":{"type":"string"}},"video":{"type":"object","properties":{"lengthSeconds":{"type":"string"},"motion":{"type":"string","enum":["stills","key","full"]},"voiceId":{"type":"string"},"pace":{"type":"string"},"language":{"type":"string"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}]},"captions":{"type":"boolean"},"captionStyle":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"cards":{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},"videoSpeed":{"type":"number"},"artStyle":{"type":"string"},"motionModel":{"description":"The AutoClips model the moving parts film with.","type":"string"},"music":{"type":"object","properties":{"mode":{"type":"string","enum":["bed","library","off"]},"trackId":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["mode","trackId","category"],"additionalProperties":false},"aspect":{"type":"string","const":"9:16"}},"required":["lengthSeconds","motion","voiceId","pace","language","locale","captions","captionStyle","cards","videoSpeed","artStyle","motionModel","music","aspect"],"additionalProperties":false}},"required":["flavor","premiseSource","premises","partsPerSeries","afterLastPart","minVoteHours","minVotes","tieBreak","direction","castCharacterIds","video"],"additionalProperties":false},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"seriesState":{"description":"Where the series is: its number, the last part posted, whether it waits for votes, the last vote.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"watermarkType":{"description":"none, text or image.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"A text watermark's words, or null.","anyOf":[{"type":"string"},{"type":"null"}]},"watermarkTextColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundOpacity":{"description":"0 to 1","type":"number"},"watermarkImageOpacity":{"description":"0.3 to 1","type":"number"},"watermarkVerticalPosition":{"description":"Percent from the top.","type":"number"},"watermarkHorizontalPosition":{"description":"Percent from the left.","type":"number"},"watermarkScale":{"description":"1 is normal.","type":"number"},"watermarkStartSeconds":{"description":"Seconds.","type":"number"},"watermarkEndSeconds":{"description":"Seconds; 0 = to the end.","type":"number"},"outroId":{"description":"Or null.","anyOf":[{"type":"string"},{"type":"null"}]},"partInProgress":{"type":"boolean"},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","status","pauseReason","schedule","topics","publishing","partInProgress","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"changed":{"description":"False when it was already paused.","type":"boolean"}},"required":["automation","changed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d","name":"Midnight Stories","status":"paused","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["18:00"],"videosPerDay":1},"series":{"flavor":"you-decide","premiseSource":"ideas","premises":[],"partsPerSeries":5,"afterLastPart":"new_series","minVoteHours":6,"minVotes":1,"tieBreak":"coin","direction":"Keep it funny.","castCharacterIds":[],"video":{"lengthSeconds":"90","motion":"stills","voiceId":"nPczCjzI2devNBz1zQrb","pace":"brisk","language":"en","locale":null,"captions":true,"captionStyle":null,"cards":{"enabled":true,"theme":null},"videoSpeed":1,"artStyle":"horror","motionModel":"autoclips1","music":{"mode":"bed","trackId":null,"category":null},"aspect":"9:16"}},"topics":{"mode":"category","category":"weird","customTopic":null,"goal":"entertain","goalText":null,"cta":"none","ctaText":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":true,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"seriesState":null,"partInProgress":false,"spendLimit":{"creditsPerDay":2750,"approvedAt":"2026-10-25T09:00:00.000Z"},"estimatedCreditsPerRun":1550,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-10-25T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-10-25T09:00:00.000Z","updatedAt":"2026-10-25T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"},"changed":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/automations/{automationId}/resume":{"post":{"operationId":"stickman_automations_resume","summary":"Resume a paused automation at its next posting time.","description":"Resumes a paused Stickman automation: it runs again from its next posting time, with its failures count reset. It needs a daily spending limit (409 spend_limit_needed: set one with set_spend_limit). A series paused because a part was deleted or changed starts a new series; one paused because it finished starts the next series. Resuming an automation that posts needs the publish permission, and AI apps ask first.\n\n**Permissions:** edit, spend.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"stickman.automations.resume","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_automations action=resume","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation (automationId from stickman_automations list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation (automationId from stickman_automations list).","example":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"video":{"description":"An Explainer or Skit automation's video.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"series":{"description":"A Story series automation's settings.","type":"object","properties":{"flavor":{"type":"string","enum":["you-decide","true-story"]},"premiseSource":{"type":"string","enum":["ideas","custom"]},"premises":{"type":"array","items":{"type":"string"}},"partsPerSeries":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"afterLastPart":{"type":"string","enum":["new_series","stop"]},"minVoteHours":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"minVotes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"tieBreak":{"type":"string","enum":["coin","a","b"]},"direction":{"anyOf":[{"type":"string"},{"type":"null"}]},"castCharacterIds":{"type":"array","items":{"type":"string"}},"video":{"type":"object","properties":{"lengthSeconds":{"type":"string"},"motion":{"type":"string","enum":["stills","key","full"]},"voiceId":{"type":"string"},"pace":{"type":"string"},"language":{"type":"string"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}]},"captions":{"type":"boolean"},"captionStyle":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"cards":{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},"videoSpeed":{"type":"number"},"artStyle":{"type":"string"},"motionModel":{"description":"The AutoClips model the moving parts film with.","type":"string"},"music":{"type":"object","properties":{"mode":{"type":"string","enum":["bed","library","off"]},"trackId":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["mode","trackId","category"],"additionalProperties":false},"aspect":{"type":"string","const":"9:16"}},"required":["lengthSeconds","motion","voiceId","pace","language","locale","captions","captionStyle","cards","videoSpeed","artStyle","motionModel","music","aspect"],"additionalProperties":false}},"required":["flavor","premiseSource","premises","partsPerSeries","afterLastPart","minVoteHours","minVotes","tieBreak","direction","castCharacterIds","video"],"additionalProperties":false},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"seriesState":{"description":"Where the series is: its number, the last part posted, whether it waits for votes, the last vote.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"watermarkType":{"description":"none, text or image.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"A text watermark's words, or null.","anyOf":[{"type":"string"},{"type":"null"}]},"watermarkTextColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundOpacity":{"description":"0 to 1","type":"number"},"watermarkImageOpacity":{"description":"0.3 to 1","type":"number"},"watermarkVerticalPosition":{"description":"Percent from the top.","type":"number"},"watermarkHorizontalPosition":{"description":"Percent from the left.","type":"number"},"watermarkScale":{"description":"1 is normal.","type":"number"},"watermarkStartSeconds":{"description":"Seconds.","type":"number"},"watermarkEndSeconds":{"description":"Seconds; 0 = to the end.","type":"number"},"outroId":{"description":"Or null.","anyOf":[{"type":"string"},{"type":"null"}]},"partInProgress":{"type":"boolean"},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","status","pauseReason","schedule","topics","publishing","partInProgress","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"changed":{"description":"False when it was already active.","type":"boolean"}},"required":["automation","changed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d","name":"Midnight Stories","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["18:00"],"videosPerDay":1},"series":{"flavor":"you-decide","premiseSource":"ideas","premises":[],"partsPerSeries":5,"afterLastPart":"new_series","minVoteHours":6,"minVotes":1,"tieBreak":"coin","direction":"Keep it funny.","castCharacterIds":[],"video":{"lengthSeconds":"90","motion":"stills","voiceId":"nPczCjzI2devNBz1zQrb","pace":"brisk","language":"en","locale":null,"captions":true,"captionStyle":null,"cards":{"enabled":true,"theme":null},"videoSpeed":1,"artStyle":"horror","motionModel":"autoclips1","music":{"mode":"bed","trackId":null,"category":null},"aspect":"9:16"}},"topics":{"mode":"category","category":"weird","customTopic":null,"goal":"entertain","goalText":null,"cta":"none","ctaText":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":true,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"seriesState":null,"partInProgress":false,"spendLimit":{"creditsPerDay":2750,"approvedAt":"2026-10-25T09:00:00.000Z"},"estimatedCreditsPerRun":1550,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-10-25T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-10-25T09:00:00.000Z","updatedAt":"2026-10-25T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"},"changed":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/automations/{automationId}/runs":{"post":{"operationId":"stickman_automations_run_now","summary":"Make the next video of an automation now, and post it as the schedule would. Answers with a job.","description":"Makes the automation's next video right now (the app's Test button) and posts it where the automation posts. For a Story series it makes the next part, counting the votes so far, and moves the series on like a scheduled run (409 series_needs_restart when the series cannot go on: restart_series; 409 series_finished when it ended and is set to stop). The price is the run at its most (an Explainer's or a Skit's clips each at their dearest, a backup clip included), plus its cover picture, plus planning when it may start Part 1 of a series; what a run does not use is given back when it is settled. One run at a time (409 run_in_progress), and at most one every 5 minutes (429). If every posting account needs reconnecting, nothing is made or charged (409 social_token_expired). An automation that posts needs the publish permission. It answers with a job (status 202): follow it with autoclips_jobs get.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.automations.run_now","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_automations action=run_now","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation (automationId from stickman_automations list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation (automationId from stickman_automations list).","example":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"run":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}},"required":["id","status"],"additionalProperties":false},"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false}},"required":["run","job"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"run":{"id":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","status":"generating"},"job":{"id":"job_019a1b2c3d4e5f60718293b5","product":"stickman","kind":"stickman.automation_run","resource":{"type":"automation_run","id":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"},"status":"queued","step":"Starting the run","progress":null,"result":null,"error":null,"createdAt":"2026-10-25T09:00:00.000Z","updatedAt":"2026-10-25T09:00:00.000Z","finishedAt":null,"poll_after_seconds":15}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"stickman_automations_runs","summary":"List an automation's recent runs: what each made, where it posted and what it used.","description":"The automation's runs, newest first: status, topic, the video it made (projectId, video link), what it used, where it posted (with a link once the post is live) and why a run failed, in plain words.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.automations.runs","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_automations action=runs","parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation (automationId from stickman_automations list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation (automationId from stickman_automations list).","example":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"},{"name":"limit","in":"query","required":false,"schema":{"description":"How many runs (1-50, default 10).","type":"integer","minimum":1,"maximum":50},"description":"How many runs (1-50, default 10).","example":5},{"name":"status","in":"query","required":false,"schema":{"description":"Only runs with this status: pending, generating, completed, failed or cancelled.","type":"string","enum":["pending","generating","completed","failed","cancelled"]},"description":"Only runs with this status: pending, generating, completed, failed or cancelled."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runs":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"testRun":{"type":"boolean"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsUsed":{"type":"number"},"posts":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"published":{"type":"boolean"},"link":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["published","link"],"additionalProperties":false}},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","testRun","topic","projectId","videoUrl","creditsUsed","posts","error","startedAt","completedAt"],"additionalProperties":false}}},"required":["runs"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"runs":[{"id":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","status":"completed","testRun":false,"topic":"Story series - Part 2","projectId":"c4a2d3e5-6f70-4b8c-9dae-1f2a3b4c5d6e","videoUrl":"https://media.autoclips.app/stickman/part-2.mp4","creditsUsed":1490,"posts":{"tiktok":{"published":true,"link":"https://www.tiktok.com/@you/video/1"}},"error":null,"startedAt":"2026-10-25T09:00:00.000Z","completedAt":"2026-10-25T09:24:00.000Z"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/automations/{automationId}/runs/cancel":{"post":{"operationId":"stickman_automations_cancel_run","summary":"Stop the run an automation is making now.","description":"Stops the run the automation is making now (or the one runId names). What it has not used yet is given back; the pictures, clips and moving scenes it already made are paid for, at what they cost (stopped before any work, everything comes back). A Story series Part 1 whose plan was still being researched pays for the research done so far, at what it really cost. 404 when no run is being made.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.automations.cancel_run","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_automations action=cancel_run","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"description":"The run to stop (from runs). Left out: the one being made now.","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation (automationId from stickman_automations list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation (automationId from stickman_automations list).","example":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runId":{"anyOf":[{"type":"string"},{"type":"null"}]},"cancelled":{"type":"boolean"},"creditsRefunded":{"description":"What came back: the part of the run's credits it had not used yet.","type":"number"}},"required":["runId","cancelled","creditsRefunded"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"runId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","cancelled":true,"creditsRefunded":1100}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/automations/{automationId}/series/restart":{"post":{"operationId":"stickman_automations_restart_series","summary":"End the series a Story automation is on: its next run starts Part 1 of a new story.","description":"The app's \"Start a new series\": ends the series the automation is on, so its next run makes Part 1 of a new story. It never resumes a paused automation. Refused while a part is being made (409 run_in_progress) and for an automation that makes no series (400 not_a_series). Mid-series it makes the next run plan Part 1 as well, so it is refused when the automation has no daily spending limit, or when a day with Part 1 planned would pass it (409 spend_limit_needed: set_spend_limit first). AI apps ask first.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.automations.restart_series","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_automations action=restart_series","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation (automationId from stickman_automations list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation (automationId from stickman_automations list).","example":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"restarted":{"description":"False when the automation had no series yet.","type":"boolean"},"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"video":{"description":"An Explainer or Skit automation's video.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"series":{"description":"A Story series automation's settings.","type":"object","properties":{"flavor":{"type":"string","enum":["you-decide","true-story"]},"premiseSource":{"type":"string","enum":["ideas","custom"]},"premises":{"type":"array","items":{"type":"string"}},"partsPerSeries":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"afterLastPart":{"type":"string","enum":["new_series","stop"]},"minVoteHours":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"minVotes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"tieBreak":{"type":"string","enum":["coin","a","b"]},"direction":{"anyOf":[{"type":"string"},{"type":"null"}]},"castCharacterIds":{"type":"array","items":{"type":"string"}},"video":{"type":"object","properties":{"lengthSeconds":{"type":"string"},"motion":{"type":"string","enum":["stills","key","full"]},"voiceId":{"type":"string"},"pace":{"type":"string"},"language":{"type":"string"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}]},"captions":{"type":"boolean"},"captionStyle":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"cards":{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},"videoSpeed":{"type":"number"},"artStyle":{"type":"string"},"motionModel":{"description":"The AutoClips model the moving parts film with.","type":"string"},"music":{"type":"object","properties":{"mode":{"type":"string","enum":["bed","library","off"]},"trackId":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["mode","trackId","category"],"additionalProperties":false},"aspect":{"type":"string","const":"9:16"}},"required":["lengthSeconds","motion","voiceId","pace","language","locale","captions","captionStyle","cards","videoSpeed","artStyle","motionModel","music","aspect"],"additionalProperties":false}},"required":["flavor","premiseSource","premises","partsPerSeries","afterLastPart","minVoteHours","minVotes","tieBreak","direction","castCharacterIds","video"],"additionalProperties":false},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"seriesState":{"description":"Where the series is: its number, the last part posted, whether it waits for votes, the last vote.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"watermarkType":{"description":"none, text or image.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"A text watermark's words, or null.","anyOf":[{"type":"string"},{"type":"null"}]},"watermarkTextColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundOpacity":{"description":"0 to 1","type":"number"},"watermarkImageOpacity":{"description":"0.3 to 1","type":"number"},"watermarkVerticalPosition":{"description":"Percent from the top.","type":"number"},"watermarkHorizontalPosition":{"description":"Percent from the left.","type":"number"},"watermarkScale":{"description":"1 is normal.","type":"number"},"watermarkStartSeconds":{"description":"Seconds.","type":"number"},"watermarkEndSeconds":{"description":"Seconds; 0 = to the end.","type":"number"},"outroId":{"description":"Or null.","anyOf":[{"type":"string"},{"type":"null"}]},"partInProgress":{"type":"boolean"},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","status","pauseReason","schedule","topics","publishing","partInProgress","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false}},"required":["restarted","automation"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"restarted":true,"automation":{"id":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d","name":"Midnight Stories","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["18:00"],"videosPerDay":1},"series":{"flavor":"you-decide","premiseSource":"ideas","premises":[],"partsPerSeries":5,"afterLastPart":"new_series","minVoteHours":6,"minVotes":1,"tieBreak":"coin","direction":"Keep it funny.","castCharacterIds":[],"video":{"lengthSeconds":"90","motion":"stills","voiceId":"nPczCjzI2devNBz1zQrb","pace":"brisk","language":"en","locale":null,"captions":true,"captionStyle":null,"cards":{"enabled":true,"theme":null},"videoSpeed":1,"artStyle":"horror","motionModel":"autoclips1","music":{"mode":"bed","trackId":null,"category":null},"aspect":"9:16"}},"topics":{"mode":"category","category":"weird","customTopic":null,"goal":"entertain","goalText":null,"cta":"none","ctaText":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":true,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"seriesState":null,"partInProgress":false,"spendLimit":{"creditsPerDay":2750,"approvedAt":"2026-10-25T09:00:00.000Z"},"estimatedCreditsPerRun":1550,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-10-25T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-10-25T09:00:00.000Z","updatedAt":"2026-10-25T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/automations/{automationId}/spend-limit":{"put":{"operationId":"stickman_automations_set_spend_limit","summary":"Set how much an automation may spend a day.","description":"Sets the automation's daily spending limit: a run that would pass it is skipped and the automation waits for the next day (a run is settled after it is made, so one step's final cost can run a little over). It must allow at least one run (400 spend_limit_too_low); for a Story series one run is a Part 1 with its planning, whatever part is next, since every new series starts with one. It resumes nothing.\n\n**Permissions:** spend.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. Stickman automation day stops before a step that would go past the limit, but one step's final cost can run a little over, so the limit is not the most it can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend"]}],"x-autoclips-operation":"stickman.automations.set_spend_limit","x-autoclips-scopes":["spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_automations action=set_spend_limit","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"spendLimitPerDay":{"description":"The most it may spend a day, in credits (1 to 100,000). Left out: one day of runs at their most.","type":"integer","minimum":1,"maximum":100000},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["spendLimitPerDay"],"additionalProperties":false},"example":{"spendLimitPerDay":3000}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation (automationId from stickman_automations list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation (automationId from stickman_automations list).","example":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"video":{"description":"An Explainer or Skit automation's video.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"series":{"description":"A Story series automation's settings.","type":"object","properties":{"flavor":{"type":"string","enum":["you-decide","true-story"]},"premiseSource":{"type":"string","enum":["ideas","custom"]},"premises":{"type":"array","items":{"type":"string"}},"partsPerSeries":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"afterLastPart":{"type":"string","enum":["new_series","stop"]},"minVoteHours":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"minVotes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"tieBreak":{"type":"string","enum":["coin","a","b"]},"direction":{"anyOf":[{"type":"string"},{"type":"null"}]},"castCharacterIds":{"type":"array","items":{"type":"string"}},"video":{"type":"object","properties":{"lengthSeconds":{"type":"string"},"motion":{"type":"string","enum":["stills","key","full"]},"voiceId":{"type":"string"},"pace":{"type":"string"},"language":{"type":"string"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}]},"captions":{"type":"boolean"},"captionStyle":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"cards":{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},"videoSpeed":{"type":"number"},"artStyle":{"type":"string"},"motionModel":{"description":"The AutoClips model the moving parts film with.","type":"string"},"music":{"type":"object","properties":{"mode":{"type":"string","enum":["bed","library","off"]},"trackId":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["mode","trackId","category"],"additionalProperties":false},"aspect":{"type":"string","const":"9:16"}},"required":["lengthSeconds","motion","voiceId","pace","language","locale","captions","captionStyle","cards","videoSpeed","artStyle","motionModel","music","aspect"],"additionalProperties":false}},"required":["flavor","premiseSource","premises","partsPerSeries","afterLastPart","minVoteHours","minVotes","tieBreak","direction","castCharacterIds","video"],"additionalProperties":false},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"seriesState":{"description":"Where the series is: its number, the last part posted, whether it waits for votes, the last vote.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"watermarkType":{"description":"none, text or image.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"A text watermark's words, or null.","anyOf":[{"type":"string"},{"type":"null"}]},"watermarkTextColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundOpacity":{"description":"0 to 1","type":"number"},"watermarkImageOpacity":{"description":"0.3 to 1","type":"number"},"watermarkVerticalPosition":{"description":"Percent from the top.","type":"number"},"watermarkHorizontalPosition":{"description":"Percent from the left.","type":"number"},"watermarkScale":{"description":"1 is normal.","type":"number"},"watermarkStartSeconds":{"description":"Seconds.","type":"number"},"watermarkEndSeconds":{"description":"Seconds; 0 = to the end.","type":"number"},"outroId":{"description":"Or null.","anyOf":[{"type":"string"},{"type":"null"}]},"partInProgress":{"type":"boolean"},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","status","pauseReason","schedule","topics","publishing","partInProgress","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false}},"required":["automation"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d","name":"Midnight Stories","status":"active","pauseReason":null,"schedule":{"timezone":"America/New_York","times":["18:00"],"videosPerDay":1},"series":{"flavor":"you-decide","premiseSource":"ideas","premises":[],"partsPerSeries":5,"afterLastPart":"new_series","minVoteHours":6,"minVotes":1,"tieBreak":"coin","direction":"Keep it funny.","castCharacterIds":[],"video":{"lengthSeconds":"90","motion":"stills","voiceId":"nPczCjzI2devNBz1zQrb","pace":"brisk","language":"en","locale":null,"captions":true,"captionStyle":null,"cards":{"enabled":true,"theme":null},"videoSpeed":1,"artStyle":"horror","motionModel":"autoclips1","music":{"mode":"bed","trackId":null,"category":null},"aspect":"9:16"}},"topics":{"mode":"category","category":"weird","customTopic":null,"goal":"entertain","goalText":null,"cta":"none","ctaText":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":true,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"seriesState":null,"partInProgress":false,"spendLimit":{"creditsPerDay":3000,"approvedAt":"2026-10-25T09:00:00.000Z"},"estimatedCreditsPerRun":1550,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-10-25T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-10-25T09:00:00.000Z","updatedAt":"2026-10-25T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/7d1c2b3a-4e5f-4a6b-9c8d-0e1f2a3b4c5d"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/capabilities":{"get":{"operationId":"stickman_capabilities_get","summary":"What this account can make right now: Story, planner, editor, voices, languages, moving scenes and series.","description":"What Stickman offers this account right now, read live (switches can change without notice): whether Stickman Story and its planner are on, the Story lengths and base prices, card looks, the editor and its prices, the narrators (with samples) and languages, moving scenes and their prices, series and series automations, My script, whether votes can be counted from your posts, and the languages an Explainer and a Skit can be spoken in. Works with Story off.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.capabilities.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_projects action=capabilities","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"storyEnabled":{"description":"Stickman Story (You Decide, True Story) is on for this account.","type":"boolean"},"agentEnabled":{"description":"The Story planner is on (stickman_plans).","type":"boolean"},"cardsRender":{"description":"On-screen text cards can be drawn.","type":"boolean"},"durations":{"description":"A Story's lengths, in seconds.","type":"array","items":{"type":"number"}},"defaultDuration":{"anyOf":[{"type":"number"},{"type":"null"}]},"themes":{"description":"Card looks.","type":"array","items":{"type":"string"}},"prices":{"description":"A Story's base by length, before the plan multiplier.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"base":{"type":"number"}},"required":["base"],"additionalProperties":false}},"agent":{"type":"object","properties":{"allowed":{"type":"boolean"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"minBalance":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["allowed","reason","minBalance"],"additionalProperties":false},"editor":{"description":"The Story editor: on or off, renders a day, and each change with its credits.","type":"object","properties":{"enabled":{"type":"boolean"},"rendersPerDay":{"anyOf":[{"type":"number"},{"type":"null"}]},"ops":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"required":["enabled","rendersPerDay","ops"],"additionalProperties":false},"languages":{"description":"The languages a Story is told in right now.","type":"object","properties":{"enabled":{"type":"boolean"},"mode":{"type":"string"},"defaultLanguage":{"type":"string"},"languages":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"nativeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"group":{"anyOf":[{"type":"string"},{"type":"null"}]},"dir":{"type":"string","enum":["ltr","rtl"]},"fixedPace":{"type":"boolean"}},"required":["code","name","nativeName","group","dir","fixedPace"],"additionalProperties":false}}},"required":["enabled","mode","defaultLanguage","languages"],"additionalProperties":false},"voices":{"description":"A Story's narrators, with a sample of each.","type":"object","properties":{"v2":{"type":"boolean"},"defaultVoiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"toneChips":{"type":"array","items":{"type":"string"}},"voices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"age":{"anyOf":[{"type":"string"},{"type":"null"}]},"accent":{"anyOf":[{"type":"string"},{"type":"null"}]},"tones":{"type":"array","items":{"type":"string"}},"native":{"type":"boolean"},"sampleUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","label","description","gender","age","accent","tones","native","sampleUrl"],"additionalProperties":false}}},"required":["v2","defaultVoiceId","toneChips","voices"],"additionalProperties":false},"castLooks":{"type":"object","properties":{"maxPerCharacter":{"anyOf":[{"type":"number"},{"type":"null"}]},"credits":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}}},"required":["maxPerCharacter","credits"],"additionalProperties":false},"motion":{"description":"Moving scenes in a Story: the tiers offered now and their prices.","type":"object","properties":{"enabled":{"type":"boolean"},"paidOnly":{"type":"boolean"},"tiers":{"type":"array","items":{"type":"string"}},"perSceneCredits":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"quotes":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"key":{"type":"object","properties":{"aboutScenes":{"type":"number"},"capScenes":{"type":"number"},"aboutCredits":{"type":"number"},"capCredits":{"type":"number"}},"required":["aboutScenes","capScenes","aboutCredits","capCredits"],"additionalProperties":false},"full":{"type":"object","properties":{"aboutScenes":{"type":"number"},"capScenes":{"type":"number"},"aboutCredits":{"type":"number"},"capCredits":{"type":"number"}},"required":["aboutScenes","capScenes","aboutCredits","capCredits"],"additionalProperties":false}},"required":["key","full"],"additionalProperties":false}}},"required":["enabled","paidOnly","tiers"],"additionalProperties":false},"series":{"type":"object","properties":{"v2":{"type":"boolean"},"chapters":{"type":"boolean"},"automation":{"type":"boolean"},"planningAtMostCredits":{"type":"number"}},"required":["v2","chapters","automation","planningAtMostCredits"],"additionalProperties":false},"myScript":{"description":"Making a Story from your own script.","type":"object","properties":{"enabled":{"type":"boolean"},"allowed":{"type":"boolean"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"minSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"maxSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"maxRawChars":{"anyOf":[{"type":"number"},{"type":"null"}]},"minLines":{"anyOf":[{"type":"number"},{"type":"null"}]},"voteQuestionMaxChars":{"anyOf":[{"type":"number"},{"type":"null"}]},"units":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["enabled","allowed","reason","minSeconds","maxSeconds","maxRawChars","minLines","voteQuestionMaxChars","units"],"additionalProperties":false},"factCheck":{"type":"string","const":"none"},"votesFromPosts":{"description":"Votes can be counted from the comments on your posts.","type":"boolean"},"seriesAutomation":{"description":"A Story series automation can be set up (stickman_automations).","type":"boolean"},"explainerLanguages":{"description":"The languages an Explainer can be spoken in right now.","type":"array","items":{"type":"string"}},"skitLanguages":{"description":"The languages a Skit can be spoken in right now.","type":"array","items":{"type":"string"}}},"required":["storyEnabled","agentEnabled","cardsRender","durations","defaultDuration","themes","prices","agent","editor","languages","voices","castLooks","motion","series","myScript","votesFromPosts","seriesAutomation","explainerLanguages","skitLanguages"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"storyEnabled":true,"agentEnabled":true,"cardsRender":true,"durations":[30,60,90,120],"defaultDuration":90,"themes":["night","ink","clean"],"prices":{"30":{"base":600},"60":{"base":1100},"90":{"base":1550},"120":{"base":2000}},"agent":{"allowed":true,"reason":null,"minBalance":300},"editor":{"enabled":true,"rendersPerDay":10,"ops":{"captions.set":{"paid":false},"picture.redraw":{"paid":true,"credits":38}}},"languages":{"enabled":false,"mode":"off","defaultLanguage":"en","languages":[{"code":"en","name":"English","nativeName":"English","group":"popular","dir":"ltr","fixedPace":false}]},"voices":{"v2":false,"defaultVoiceId":"nPczCjzI2devNBz1zQrb","toneChips":["deadpan","storyteller","dramatic","bright"],"voices":[{"id":"nPczCjzI2devNBz1zQrb","label":"Brian","description":"Deep, relentless deadpan","gender":"male","age":"middle","accent":"American","tones":["deadpan"],"native":false,"sampleUrl":"https://app.autoclips.app/stickman/voices/nPczCjzI2devNBz1zQrb-v2.mp3"}]},"castLooks":{"maxPerCharacter":5,"credits":{"regenerate":60,"regeneratePhoto":65,"photo":65,"edit":45}},"motion":{"enabled":true,"paidOnly":true,"tiers":["stills","key","full"],"perSceneCredits":{"5":173,"10":339,"15":506},"quotes":{"90":{"key":{"aboutScenes":9,"capScenes":16,"aboutCredits":1557,"capCredits":2768},"full":{"aboutScenes":16,"capScenes":23,"aboutCredits":2768,"capCredits":3979}}}},"series":{"v2":true,"chapters":false,"automation":false,"planningAtMostCredits":1200},"myScript":{"enabled":false,"allowed":false,"reason":null,"minSeconds":20,"maxSeconds":120,"maxRawChars":2000,"minLines":6,"voteQuestionMaxChars":40,"units":{"version":1,"pictureScene":25}},"votesFromPosts":true,"seriesAutomation":false,"explainerLanguages":["en","es","fr"],"skitLanguages":["en","es"]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/cast":{"get":{"operationId":"stickman_cast_list","summary":"List the characters saved in your My cast.","description":"List the characters saved in your My cast.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.cast.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_cast action=list","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"characters":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The character id. Use it in castCharacterIds of stickman_plans create, or to swap or add a cast member on a plan.","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"aliases":{"description":"Other names the script may call the character.","type":"array","items":{"type":"string"}},"realPerson":{"description":"True when the character is a real person.","type":"boolean"},"pickedVariant":{"description":"Which of the variants is the character's picture (0 for the first).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"variants":{"description":"The stick pictures drawn for the character; pickedVariant says which one stories use.","type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"look":{"description":"A photo is drawn in three looks: face (their face on the white stickman head), likeness (most like them, in their skin colour) and classic (the white ball head with their hair).","type":"string"}},"required":["url"],"additionalProperties":false}},"masterUrl":{"description":"The picture stories use.","anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"description":"A small version of that picture, for lists.","anyOf":[{"type":"string"},{"type":"null"}]},"signatureColor":{"description":"The colour the character wears most.","anyOf":[{"type":"string"},{"type":"null"}]},"conversionPath":{"description":"How the picture was made: photo (drawn from a photo or a drawing of a person), traits (from a description) or drawing (your own stickman, kept exactly as you uploaded it).","anyOf":[{"type":"string"},{"type":"null"}]},"about":{"description":"Who the character is, in your words; null when not set.","anyOf":[{"type":"string"},{"type":"null"}]},"look":{"description":"The look of the picked picture (face, likeness or classic); null for a character with no looks.","anyOf":[{"type":"string"},{"type":"null"}]},"voice":{"description":"The voice the character speaks in. null for a character saved before voices: one that fits is picked when a story uses them.","anyOf":[{"type":"object","properties":{"id":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"mine":{"description":"True for one of your own cloned voices.","type":"boolean"}},"required":["id","label","description","mine"],"additionalProperties":false},{"type":"null"}]},"group":{"description":"kept: you made it, or a video used it again. video: a story drew it for one video and it joined My cast by itself; when My cast is full, the oldest of these not used again makes room.","type":"string","enum":["kept","video"]},"chargedCredits":{"description":"What making the character was charged, in credits (0 for your own stickman).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"usageCount":{"description":"How many videos used the character.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lastUsedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","aliases","realPerson","pickedVariant","variants","masterUrl","posterUrl","signatureColor","conversionPath","about","usageCount","lastUsedAt","createdAt","updatedAt"],"additionalProperties":false}}},"required":["characters"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"characters":[{"id":"3f2b6c1e-8a4d-4b7e-9c2f-1d5e6a7b8c9d","name":"Gary","aliases":["Big G"],"realPerson":false,"pickedVariant":1,"variants":[{"url":"https://media.autoclips.app/stickman/cast/3f2b6c1e-v0.png"},{"url":"https://media.autoclips.app/stickman/cast/3f2b6c1e-v1.png"},{"url":"https://media.autoclips.app/stickman/cast/3f2b6c1e-v2.png"}],"masterUrl":"https://media.autoclips.app/stickman/cast/3f2b6c1e-v1.png","posterUrl":"https://media.autoclips.app/stickman/cast/3f2b6c1e-v1-poster.jpg","signatureColor":"teal","conversionPath":"photo","about":"my cousin, a talker who never stops","usageCount":2,"lastUsedAt":"2026-10-20T09:00:00.000Z","createdAt":"2026-10-18T14:30:00.000Z","updatedAt":"2026-10-20T09:00:00.000Z"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"stickman_cast_create","summary":"Add a character to My cast from a picture (your own stickman is kept as it is; a photo is drawn in three looks to pick from) or a name.","description":"Keeps a character in My cast. With an uploadId (stickman_story upload_image) the picture decides: your own stickman drawing is kept exactly as it is (nothing is drawn, nothing charged); a photo of a person, or another drawing of one, is drawn in three looks: face (their face on the white stickman head), likeness (most like them, in their skin colour) and classic (the white ball head with their hair). The first (face) is picked; pick another with update pickedVariant. A child, or a picture with no person or character in it, is refused. Without an uploadId, a stickman is drawn from its name. about says who they are; a story casts the first character you pick as its lead unless the story or about says otherwise. Paid plans only, and at most 100 characters (delete one to make room). A drawn character is charged at what it really costs ($1 = 600 credits): the limit you approve is the most the run can be charged, and pictures thrown away by our checks are not charged. The pictures also count toward the account's daily stick-picture limit. It answers when the pictures are drawn: about a minute from a name, a few minutes for the three looks of a photo (never more than about five). The same name and photo again within two minutes hands back the character the first call made (alreadyMade: true).\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. The limit is the most My cast character can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.cast.create","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_cast action=create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The character's name, 1 to 32 characters. Scripts call the character by it.","type":"string","minLength":1,"maxLength":32},"uploadId":{"description":"A picture added with stickman_story upload_image.","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"about":{"description":"Who the character is, in your words (up to 200 characters), e.g. \"my channel's mascot, always curious, never gives up\". The story writer reads it. Leave it out and a story casts your first character as its lead.","type":"string","maxLength":200},"realPerson":{"description":"True when the character is a real person.","type":"boolean"},"voiceId":{"description":"The voice the character speaks in, whenever they talk in a video: one of the Story voices (stickman.capabilities.get, voices), or the voiceId of one of your own cloned voices (autoclips_voices, source \"cloned\"). Leave it out and a voice that fits them is picked. A real person never gets a copy of their real voice unless it is a clone you made with their permission.","type":"string","pattern":"^[A-Za-z0-9]{8,64}$"},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["name"],"additionalProperties":false},"example":{"name":"Priya"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"character":{"type":"object","properties":{"id":{"description":"The character id. Use it in castCharacterIds of stickman_plans create, or to swap or add a cast member on a plan.","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"aliases":{"description":"Other names the script may call the character.","type":"array","items":{"type":"string"}},"realPerson":{"description":"True when the character is a real person.","type":"boolean"},"pickedVariant":{"description":"Which of the variants is the character's picture (0 for the first).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"variants":{"description":"The stick pictures drawn for the character; pickedVariant says which one stories use.","type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"look":{"description":"A photo is drawn in three looks: face (their face on the white stickman head), likeness (most like them, in their skin colour) and classic (the white ball head with their hair).","type":"string"}},"required":["url"],"additionalProperties":false}},"masterUrl":{"description":"The picture stories use.","anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"description":"A small version of that picture, for lists.","anyOf":[{"type":"string"},{"type":"null"}]},"signatureColor":{"description":"The colour the character wears most.","anyOf":[{"type":"string"},{"type":"null"}]},"conversionPath":{"description":"How the picture was made: photo (drawn from a photo or a drawing of a person), traits (from a description) or drawing (your own stickman, kept exactly as you uploaded it).","anyOf":[{"type":"string"},{"type":"null"}]},"about":{"description":"Who the character is, in your words; null when not set.","anyOf":[{"type":"string"},{"type":"null"}]},"look":{"description":"The look of the picked picture (face, likeness or classic); null for a character with no looks.","anyOf":[{"type":"string"},{"type":"null"}]},"voice":{"description":"The voice the character speaks in. null for a character saved before voices: one that fits is picked when a story uses them.","anyOf":[{"type":"object","properties":{"id":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"mine":{"description":"True for one of your own cloned voices.","type":"boolean"}},"required":["id","label","description","mine"],"additionalProperties":false},{"type":"null"}]},"group":{"description":"kept: you made it, or a video used it again. video: a story drew it for one video and it joined My cast by itself; when My cast is full, the oldest of these not used again makes room.","type":"string","enum":["kept","video"]},"chargedCredits":{"description":"What making the character was charged, in credits (0 for your own stickman).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"usageCount":{"description":"How many videos used the character.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lastUsedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","aliases","realPerson","pickedVariant","variants","masterUrl","posterUrl","signatureColor","conversionPath","about","usageCount","lastUsedAt","createdAt","updatedAt"],"additionalProperties":false},"alreadyMade":{"description":"True when a call with the same name and photo made this character in the last two minutes: nothing new was drawn.","type":"boolean"}},"required":["character","alreadyMade"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"character":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","name":"Priya","aliases":[],"realPerson":false,"pickedVariant":0,"variants":[{"url":"https://media.autoclips.app/stickman/cast/9a8b7c6d-v0.png"}],"masterUrl":"https://media.autoclips.app/stickman/cast/9a8b7c6d-v0.png","posterUrl":"https://media.autoclips.app/stickman/cast/9a8b7c6d-v0-poster.jpg","signatureColor":"coral","conversionPath":"traits","about":null,"usageCount":0,"lastUsedAt":null,"createdAt":"2026-10-21T08:00:00.000Z","updatedAt":"2026-10-21T08:00:00.000Z"},"alreadyMade":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/cast/presets":{"get":{"operationId":"stickman_cast_presets","summary":"List the ready-made Stickman characters any story can use (ids preset:<slug>).","description":"Ten styled stick characters, five men and five women, that any Story can cast without making one: use a preset's id (preset:<slug>) wherever a character id goes.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.cast.presets","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_cast action=presets","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"presets":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The preset id, preset:<slug>. Use it like a character id.","type":"string"},"name":{"type":"string"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"vibe":{"description":"The part the preset is made for, in a few words.","anyOf":[{"type":"string"},{"type":"null"}]},"traits":{"description":"How the preset looks: hair, clothes, build and so on.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"signatureColor":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"description":"Its picture, once drawn; null until then (it is drawn from its words).","anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","gender","vibe","traits","signatureColor","masterUrl","posterUrl"],"additionalProperties":false}}},"required":["presets"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"presets":[{"id":"preset:max","name":"Max","gender":"male","vibe":"the everyday lead","traits":{"hair":"messy dark-brown quiff swept up at the front","top":"mustard-yellow hoodie over a white tee","build":"average","accessories":["black wristwatch"]},"signatureColor":"mustard yellow","masterUrl":null,"posterUrl":null}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/cast/{characterId}":{"patch":{"operationId":"stickman_cast_update","summary":"Rename a My cast character, say who they are, change its voice, set its other names or pick another of its pictures.","description":"Send at least one of name, about (who they are; \"\" clears it), aliases (up to 4 other names, each different), pickedVariant (which of its pictures stories use, from its variants), realPerson or voiceId (the voice it speaks in). Videos already made keep the character as it was.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.cast.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_cast action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The character's name, 1 to 32 characters. Scripts call the character by it.","type":"string","minLength":1,"maxLength":32},"aliases":{"description":"Other names the script may call the character (up to 4, each different). Replaces the list; [] clears it.","maxItems":4,"type":"array","items":{"type":"string","minLength":1,"maxLength":32}},"pickedVariant":{"description":"Which of its variants stories use (0 for the first). A photo character has one per look (variants[].look: face, likeness, classic).","type":"integer","minimum":0,"maximum":17},"realPerson":{"description":"True when the character is a real person.","type":"boolean"},"about":{"description":"Who the character is, in your words (up to 200 characters), e.g. \"my channel's mascot, always curious, never gives up\". The story writer reads it. Leave it out and a story casts your first character as its lead.","type":"string","maxLength":200},"voiceId":{"description":"The voice the character speaks in, whenever they talk in a video: one of the Story voices (stickman.capabilities.get, voices), or the voiceId of one of your own cloned voices (autoclips_voices, source \"cloned\"). Leave it out and a voice that fits them is picked. A real person never gets a copy of their real voice unless it is a clone you made with their permission.","type":"string","pattern":"^[A-Za-z0-9]{8,64}$"}},"additionalProperties":false},"example":{"aliases":["Big G"]}}}},"parameters":[{"name":"characterId","in":"path","required":true,"schema":{"description":"The cast member (characterId from stickman_cast list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The cast member (characterId from stickman_cast list).","example":"3f2b6c1e-8a4d-4b7e-9c2f-1d5e6a7b8c9d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"character":{"type":"object","properties":{"id":{"description":"The character id. Use it in castCharacterIds of stickman_plans create, or to swap or add a cast member on a plan.","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"aliases":{"description":"Other names the script may call the character.","type":"array","items":{"type":"string"}},"realPerson":{"description":"True when the character is a real person.","type":"boolean"},"pickedVariant":{"description":"Which of the variants is the character's picture (0 for the first).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"variants":{"description":"The stick pictures drawn for the character; pickedVariant says which one stories use.","type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"look":{"description":"A photo is drawn in three looks: face (their face on the white stickman head), likeness (most like them, in their skin colour) and classic (the white ball head with their hair).","type":"string"}},"required":["url"],"additionalProperties":false}},"masterUrl":{"description":"The picture stories use.","anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"description":"A small version of that picture, for lists.","anyOf":[{"type":"string"},{"type":"null"}]},"signatureColor":{"description":"The colour the character wears most.","anyOf":[{"type":"string"},{"type":"null"}]},"conversionPath":{"description":"How the picture was made: photo (drawn from a photo or a drawing of a person), traits (from a description) or drawing (your own stickman, kept exactly as you uploaded it).","anyOf":[{"type":"string"},{"type":"null"}]},"about":{"description":"Who the character is, in your words; null when not set.","anyOf":[{"type":"string"},{"type":"null"}]},"look":{"description":"The look of the picked picture (face, likeness or classic); null for a character with no looks.","anyOf":[{"type":"string"},{"type":"null"}]},"voice":{"description":"The voice the character speaks in. null for a character saved before voices: one that fits is picked when a story uses them.","anyOf":[{"type":"object","properties":{"id":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"mine":{"description":"True for one of your own cloned voices.","type":"boolean"}},"required":["id","label","description","mine"],"additionalProperties":false},{"type":"null"}]},"group":{"description":"kept: you made it, or a video used it again. video: a story drew it for one video and it joined My cast by itself; when My cast is full, the oldest of these not used again makes room.","type":"string","enum":["kept","video"]},"chargedCredits":{"description":"What making the character was charged, in credits (0 for your own stickman).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"usageCount":{"description":"How many videos used the character.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lastUsedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","aliases","realPerson","pickedVariant","variants","masterUrl","posterUrl","signatureColor","conversionPath","about","usageCount","lastUsedAt","createdAt","updatedAt"],"additionalProperties":false}},"required":["character"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"character":{"id":"3f2b6c1e-8a4d-4b7e-9c2f-1d5e6a7b8c9d","name":"Gary","aliases":["Big G"],"realPerson":false,"pickedVariant":1,"variants":[{"url":"https://media.autoclips.app/stickman/cast/3f2b6c1e-v0.png"},{"url":"https://media.autoclips.app/stickman/cast/3f2b6c1e-v1.png"},{"url":"https://media.autoclips.app/stickman/cast/3f2b6c1e-v2.png"}],"masterUrl":"https://media.autoclips.app/stickman/cast/3f2b6c1e-v1.png","posterUrl":"https://media.autoclips.app/stickman/cast/3f2b6c1e-v1-poster.jpg","signatureColor":"teal","conversionPath":"photo","about":"my cousin, a talker who never stops","usageCount":2,"lastUsedAt":"2026-10-20T09:00:00.000Z","createdAt":"2026-10-18T14:30:00.000Z","updatedAt":"2026-10-20T09:00:00.000Z"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"stickman_cast_delete","summary":"Delete a character from My cast. Videos that already use it keep it.","description":"Removes the character from My cast, so new stories cannot cast it. Videos and plans that already use it keep its pictures.\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"stickman.cast.delete","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_cast action=delete","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"characterId","in":"path","required":true,"schema":{"description":"The cast member (characterId from stickman_cast list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The cast member (characterId from stickman_cast list).","example":"3f2b6c1e-8a4d-4b7e-9c2f-1d5e6a7b8c9d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"},"characterId":{"type":"string"}},"required":["deleted","characterId"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"deleted":true,"characterId":"3f2b6c1e-8a4d-4b7e-9c2f-1d5e6a7b8c9d"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/cast/{characterId}/redraw":{"post":{"operationId":"stickman_cast_redraw","summary":"Draw new looks for a My cast character; they are added to its pictures and the best one is used.","description":"Draws the character again: a character made from a photo in its three looks (face, likeness, classic) from that photo, any other in new versions from how it looks. The new pictures are added to its variants (its old ones stay, up to 18) and the best new one becomes the picture stories use; pick another with update pickedVariant. Paid plans only. Charged at what it really costs ($1 = 600 credits): the limit you approve is the most the run can be charged, and nothing is charged if it fails. The pictures count toward the daily stick-picture limit. It answers when they are drawn: about a minute, a few minutes for a photo's three looks.\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. The limit is the most New looks for a My cast character can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.cast.redraw","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_cast action=redraw","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"characterId","in":"path","required":true,"schema":{"description":"The cast member (characterId from stickman_cast list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The cast member (characterId from stickman_cast list).","example":"3f2b6c1e-8a4d-4b7e-9c2f-1d5e6a7b8c9d"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"character":{"type":"object","properties":{"id":{"description":"The character id. Use it in castCharacterIds of stickman_plans create, or to swap or add a cast member on a plan.","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"aliases":{"description":"Other names the script may call the character.","type":"array","items":{"type":"string"}},"realPerson":{"description":"True when the character is a real person.","type":"boolean"},"pickedVariant":{"description":"Which of the variants is the character's picture (0 for the first).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"variants":{"description":"The stick pictures drawn for the character; pickedVariant says which one stories use.","type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"look":{"description":"A photo is drawn in three looks: face (their face on the white stickman head), likeness (most like them, in their skin colour) and classic (the white ball head with their hair).","type":"string"}},"required":["url"],"additionalProperties":false}},"masterUrl":{"description":"The picture stories use.","anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"description":"A small version of that picture, for lists.","anyOf":[{"type":"string"},{"type":"null"}]},"signatureColor":{"description":"The colour the character wears most.","anyOf":[{"type":"string"},{"type":"null"}]},"conversionPath":{"description":"How the picture was made: photo (drawn from a photo or a drawing of a person), traits (from a description) or drawing (your own stickman, kept exactly as you uploaded it).","anyOf":[{"type":"string"},{"type":"null"}]},"about":{"description":"Who the character is, in your words; null when not set.","anyOf":[{"type":"string"},{"type":"null"}]},"look":{"description":"The look of the picked picture (face, likeness or classic); null for a character with no looks.","anyOf":[{"type":"string"},{"type":"null"}]},"voice":{"description":"The voice the character speaks in. null for a character saved before voices: one that fits is picked when a story uses them.","anyOf":[{"type":"object","properties":{"id":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"mine":{"description":"True for one of your own cloned voices.","type":"boolean"}},"required":["id","label","description","mine"],"additionalProperties":false},{"type":"null"}]},"group":{"description":"kept: you made it, or a video used it again. video: a story drew it for one video and it joined My cast by itself; when My cast is full, the oldest of these not used again makes room.","type":"string","enum":["kept","video"]},"chargedCredits":{"description":"What making the character was charged, in credits (0 for your own stickman).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"usageCount":{"description":"How many videos used the character.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lastUsedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","aliases","realPerson","pickedVariant","variants","masterUrl","posterUrl","signatureColor","conversionPath","about","usageCount","lastUsedAt","createdAt","updatedAt"],"additionalProperties":false},"drawn":{"description":"How many new pictures were added.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["character","drawn"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/fixes/{fixId}":{"get":{"operationId":"stickman_fixes_get","summary":"Read a Fix this request: where it is, and its plan or question once it answers.","description":"Reads a Fix this request: its status (queued, locating, reading, thinking, ready, applying, done, failed, cancelled), its last events, and once ready its plan (steps with ids, whether each is paid and its credits) or its question (options to pick with fix_answer), what the look was charged and what was applied.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.fixes.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_edit action=fix_status","parameters":[{"name":"fixId","in":"path","required":true,"schema":{"description":"The Fix this run (fixId from stickman_edit fix).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Fix this run (fixId from stickman_edit fix).","example":"er_3f9a1c7e5b2d4a6c8e0f"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"fix":{"description":"The Fix this request: its status, its plan (steps with ids and credits) or question, what it was charged, and what was applied.","type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"request":{"anyOf":[{"type":"string"},{"type":"null"}]},"plan":{"anyOf":[{"type":"object","properties":{"kind":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind"],"additionalProperties":{}},{"type":"null"}]},"billing":{"type":"object","properties":{"lookCredits":{"type":"number"},"chargedCredits":{"type":"number"}},"required":["lookCredits","chargedCredits"],"additionalProperties":false}},"required":["id","projectId","status","request","plan","billing"],"additionalProperties":{}}},"required":["fix"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"fix":{"id":"er_3f9a1c7e5b2d4a6c8e0f","projectId":"6f1d2c9a-3b7e-4f58-a0d4-9c2e7b1a5f30","scope":{"kind":"scene","sceneIndex":4},"request":"The door should be open in this scene.","status":"ready","events":[{"at":"2026-10-25T10:00:40.000Z","kind":"ready","text":"Here is a fix."}],"plan":{"kind":"plan","steps":[{"id":"s1","type":"picture.redraw","sceneIndex":4,"summary":"Draw scene 5 again with the door open","paid":true,"credits":45,"creditsAtMost":45}]},"screenshot":null,"billing":{"lookCredits":31,"chargedCredits":31},"looks":1,"applied":null,"error":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:40.000Z"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/fixes/{fixId}/answer":{"post":{"operationId":"stickman_fixes_answer","summary":"Answer a Fix this question by picking one of its options.","description":"When Fix this answered with a question, picks one of its options (plan.options, from 0): its steps become the plan, with no new look. Then apply the steps you want with fix_apply.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.fixes.answer","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_edit action=fix_answer","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"option":{"description":"The option to pick (plan.options, from 0).","type":"integer","minimum":0,"maximum":2}},"required":["option"],"additionalProperties":false},"example":{"option":0}}}},"parameters":[{"name":"fixId","in":"path","required":true,"schema":{"description":"The Fix this run (fixId from stickman_edit fix).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Fix this run (fixId from stickman_edit fix).","example":"er_3f9a1c7e5b2d4a6c8e0f"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"fix":{"description":"The Fix this request: its status, its plan (steps with ids and credits) or question, what it was charged, and what was applied.","type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"request":{"anyOf":[{"type":"string"},{"type":"null"}]},"plan":{"anyOf":[{"type":"object","properties":{"kind":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind"],"additionalProperties":{}},{"type":"null"}]},"billing":{"type":"object","properties":{"lookCredits":{"type":"number"},"chargedCredits":{"type":"number"}},"required":["lookCredits","chargedCredits"],"additionalProperties":false}},"required":["id","projectId","status","request","plan","billing"],"additionalProperties":{}}},"required":["fix"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/fixes/{fixId}/apply":{"post":{"operationId":"stickman_fixes_apply","summary":"Apply the ticked steps of a Fix this plan. Paid steps answer with a job.","description":"Applies the steps you tick of a ready Fix this plan as one batch (undo it whole with undo fixId). Steps that make nothing new apply at once; paid steps run as paid changes, each charged at what it really costs when it works, never above its line, and not charged when it fails (the price is theirs, 0 when every ticked step makes nothing new). With paid steps it answers with a job (status 202). A fix applies once: a second apply is 409 run_busy; 409 plan_stale when the video changed so a step no longer fits (ask it again with fix_message).\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.fixes.apply","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_edit action=fix_apply","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stepIds":{"description":"The plan steps to apply (plan.steps[].id from fix_status).","minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":40}},"baseRevision":{"description":"The editing.revision you read (stickman_projects get, include editing); an older one is refused (409 stale_revision).","type":"integer","minimum":0,"maximum":9007199254740991},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"required":["stepIds","baseRevision"],"additionalProperties":false},"example":{"stepIds":["s1"],"baseRevision":4}}}},"parameters":[{"name":"fixId","in":"path","required":true,"schema":{"description":"The Fix this run (fixId from stickman_edit fix).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Fix this run (fixId from stickman_edit fix).","example":"er_3f9a1c7e5b2d4a6c8e0f"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"editIds":{"type":"array","items":{"type":"string"}},"project":{"description":"The video after the change (see stickman_projects get), with its editing state and scenes.","type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"type":"string"},"title":{"type":"string"},"stage":{"type":"string"},"status":{"type":"string"},"editing":{"anyOf":[{"type":"object","properties":{"revision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["revision"],"additionalProperties":{}},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","kind","title","stage","status"],"additionalProperties":{}},"fix":{"anyOf":[{"description":"The Fix this request: its status, its plan (steps with ids and credits) or question, what it was charged, and what was applied.","type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"request":{"anyOf":[{"type":"string"},{"type":"null"}]},"plan":{"anyOf":[{"type":"object","properties":{"kind":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind"],"additionalProperties":{}},{"type":"null"}]},"billing":{"type":"object","properties":{"lookCredits":{"type":"number"},"chargedCredits":{"type":"number"}},"required":["lookCredits","chargedCredits"],"additionalProperties":false}},"required":["id","projectId","status","request","plan","billing"],"additionalProperties":{}},{"type":"null"}]},"job":{"description":"Present when paid steps run: follow it with autoclips_jobs get.","anyOf":[{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},{"type":"null"}]},"approvedCredits":{"description":"What you approved for this call. Nothing is charged until each part works; the job settles it to what was really charged.","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["editIds","project","fix","job","approvedCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/fixes/{fixId}/cancel":{"post":{"operationId":"stickman_fixes_cancel","summary":"Stop a Fix this request before it answers.","description":"Stops a Fix this request that has not answered yet; a stopped look is never charged. 409 already_answered when it answered first (read the plan), already_applied once it is in the video (undo it with undo fixId).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.fixes.cancel","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_edit action=fix_cancel","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"fixId","in":"path","required":true,"schema":{"description":"The Fix this run (fixId from stickman_edit fix).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Fix this run (fixId from stickman_edit fix).","example":"er_3f9a1c7e5b2d4a6c8e0f"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"fix":{"description":"The Fix this request: its status, its plan (steps with ids and credits) or question, what it was charged, and what was applied.","type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"request":{"anyOf":[{"type":"string"},{"type":"null"}]},"plan":{"anyOf":[{"type":"object","properties":{"kind":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind"],"additionalProperties":{}},{"type":"null"}]},"billing":{"type":"object","properties":{"lookCredits":{"type":"number"},"chargedCredits":{"type":"number"}},"required":["lookCredits","chargedCredits"],"additionalProperties":false}},"required":["id","projectId","status","request","plan","billing"],"additionalProperties":{}}},"required":["fix"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/fixes/{fixId}/message":{"post":{"operationId":"stickman_fixes_message","summary":"Tell Fix this what should be different: it looks again. Answers with a job.","description":"Tells Fix this what should be different about its answer: it reads the video again and answers with a new plan or question. The new look is charged at what it really costs when it answers, never above the price, and counts as one of the 30 fixes a day. It answers with a job (status 202).\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.fixes.message","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_edit action=fix_message","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"description":"What should be different, in plain words.","type":"string","minLength":1,"maxLength":600},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"required":["message"],"additionalProperties":false},"example":{"message":"Keep the picture, just show more of the room."}}}},"parameters":[{"name":"fixId","in":"path","required":true,"schema":{"description":"The Fix this run (fixId from stickman_edit fix).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Fix this run (fixId from stickman_edit fix).","example":"er_3f9a1c7e5b2d4a6c8e0f"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"fix":{"description":"The fix (fixId) and its status.","type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}},"required":["id","status"],"additionalProperties":false},"job":{"anyOf":[{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},{"type":"null"}]},"approvedCredits":{"description":"What you approved for this call. Nothing is charged until each part works; the job settles it to what was really charged.","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["fix","job","approvedCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/ideas":{"get":{"operationId":"stickman_ideas_list","summary":"Today's fresh video ideas: a label, the topic to send to create, its angle and mode.","description":"The idea chips the Stickman page shows today (refreshed daily, or evergreen ones while none were made). Each has a short label, a topic you can send to create as is, its angle and its mode.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.ideas.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_projects action=ideas","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ideas":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"scenario":{"type":"string"},"angle":{"anyOf":[{"type":"string"},{"type":"null"}]},"mode":{"type":"string","enum":["explainer","skit"]}},"required":["label","scenario","angle","mode"],"additionalProperties":false}},"day":{"description":"The day these ideas were made (UTC), or null for the evergreen ones.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ideas","day"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"ideas":[{"label":"Sell Air From Famous Cities","scenario":"A deadpan business plan for bottling plain air, labeling each jar by city, and scaling the operation into a subscription empire","angle":"unethical-money","mode":"explainer"}],"day":"2026-10-25"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/plans":{"post":{"operationId":"stickman_plans_create","summary":"Have the Director research and plan a Stickman Story. What you approve is the planning's spending limit.","description":"The Director reads your idea (or your own script), researches it (a True Story is checked against sources), plans the scenes, the vote or the ending, and draws the cast and places. It may ask you ONE question: answer it with answer. Planning is charged at what it really cost when the plan is ready, never above the limit you approve, the most the run can be charged (default 1,200 credits, 600 for a script); a plan that fails is not charged. Paid plans only. It answers with a job at once (status 202); when the plan is ready, read it with get, change it, then make_video.\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. The limit is the most Stickman Story plan can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.plans.create","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_plans action=create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idea":{"description":"What the story is about, 3 to 2,000 characters. Send idea or script, not both.","type":"string","minLength":3,"maxLength":2000},"script":{"description":"Your own script (My script), up to 2,000 characters: the Director plans the pictures and cast for your words.","type":"string","minLength":1,"maxLength":4000},"flavor":{"description":"you-decide, true-story, or auto (the Director picks from your idea; idea only). Default auto, or you-decide for a script.","type":"string","enum":["you-decide","true-story","auto"]},"lengthSeconds":{"description":"The video's length (an idea only: a script sets its own).","type":"string","enum":["30","40","50","60","70","80","90","100","110","120"]},"pictures":{"description":"Up to 8 pictures (stickman_story upload_image) of people, logos or props for the story.","maxItems":8,"type":"array","items":{"type":"object","properties":{"uploadId":{"description":"A picture added with stickman_story upload_image.","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"caption":{"description":"Who or what it is, up to 80 characters.","type":"string","maxLength":80}},"required":["uploadId"],"additionalProperties":false}},"castCharacterIds":{"description":"Up to 4 My cast ids (stickman_cast list) or \"preset:<slug>\" the story must cast.","maxItems":4,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"reuseCast":{"description":"Reuse My cast (default true): when the story needs someone already in My cast (the same real person, or a character the story names), they come back with the same picture and voice instead of being drawn again. false draws everyone new. Either way, everyone the video shows joins My cast when it is made.","type":"boolean"},"language":{"title":"Language (Story) (Stickman videos (Explainer, Skit, Story) option storyLanguage)","description":"Language (Story): The language of a Story's narration, cards and captions. Some languages are switched on later than others: a language that is not offered yet is refused with language_not_offered, and stickman.capabilities.get lists what is offered now.\nChoices: one of 94 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=storyLanguage) to see them all.\nDefault: en.","type":"string"},"locale":{"description":"Language variant: Which variant of a Story language to use, for the languages that have one (meta.language). Leave it out for the language's usual variant.\nChoices:\n- es-419 — Spanish (Latin America): Spanish as spoken in Latin America.\n- es-ES — Spanish (Spain): Spanish as spoken in Spain.\n- es-MX — Spanish (Mexico): Spanish as spoken in Mexico.\n- pt-BR — Portuguese (Brazil): Portuguese as spoken in Brazil.\n- pt-PT — Portuguese (Portugal): Portuguese as spoken in Portugal.\n- bn-BD — Bengali (Bangladesh): Bengali as spoken in Bangladesh.\n- bn-IN — Bengali (India): Bengali as spoken in India.\nDefault: The language's usual variant (leave it out).","type":"string","enum":["es-419","es-ES","es-MX","pt-BR","pt-PT","bn-BD","bn-IN"]},"voiceId":{"description":"Narrator (Story): Who reads a Story. The last 14 (meta.v2Only) need the 20-voice switch; stickman.capabilities.get lists what is offered now. meta.sampleUrl plays a sample.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=storyVoice) to see them all.\nDefault: nPczCjzI2devNBz1zQrb. Or the voiceId of one of your own cloned voices (autoclips_voices, source \"cloned\").","type":"string","pattern":"^[A-Za-z0-9]{8,64}$"},"pace":{"description":"Reading pace: How fast the narrator reads. A faster pace fits more words into the same length.\nChoices:\n- relaxed — Relaxed: Everyday speaking pace — easiest to follow.\n- natural — Natural: Steady documentary read.\n- brisk — Brisk: Fast and punchy, still every word clear.\n- rapid — Rapid: Breathless, relentless — the hardest read to follow.\nDefault: brisk.","type":"string","enum":["relaxed","natural","brisk","rapid"]},"vote":{"description":"A My script's end-card vote.","type":"object","properties":{"question":{"description":"The end card's question, 3 to 40 characters.","type":"string","minLength":3,"maxLength":40},"a":{"description":"The first choice, one short word.","type":"string","minLength":1,"maxLength":14},"b":{"description":"The second choice, one short word.","type":"string","minLength":1,"maxLength":14}},"required":["question","a","b"],"additionalProperties":false},"languageConfirmed":{"description":"A My script: read it in the language picked even though the words look like another.","type":"boolean"},"formatId":{"description":"The formatId format_script answered for this script.","type":"string","pattern":"^[0-9a-f-]{8,64}$"},"scriptNotes":{"description":"The picture notes format_script found (place, action, speaker by paragraph).","maxItems":60,"type":"array","items":{"type":"object","properties":{"paragraph":{"description":"Which paragraph of the script (from 0).","type":"integer","minimum":0,"maximum":200},"place":{"type":"string","maxLength":200},"action":{"type":"string","maxLength":200},"speaker":{"type":"string","maxLength":60}},"required":["paragraph"],"additionalProperties":false}},"planningLimit":{"description":"The planning's spending limit, 300 to 2,400 credits. Default 1,200 (600 for a script).","type":"integer","minimum":300,"maximum":2400},"plannedParts":{"description":"Planned parts: How many parts a Story series is planned to have, so Part 1 is paced as the start of a longer story and the last part ends it. Needs the chapters switch (stickman.capabilities.get series.chapters). From 2 to 20 parts. Default: No set number of parts (leave it out).","type":"integer","minimum":2,"maximum":20},"artStyle":{"description":"Art style: The look of the pictures in a Story: the places, the light and the colours. The stick figures stay the same in every style. A next part keeps the style of the part before it. meta.exampleUrl shows the same scene in each style.\nChoices:\n- default — Cinematic: Painted night scenes in teal and warm orange. The classic look. Best for any story.\n- horror — Horror Glow: Dark and creepy, lit by vivid green, red and purple light. Best for scary, survival and mystery stories.\n- noir — Rainy Noir: Rain-soaked streets, hard shadows and cold blue light. Crime and secrets. Best for crime, heists and true stories.\n- sunny — Bright Day: Sunny, colourful and cheerful, like a Saturday-morning cartoon. Best for funny, feel-good and kids stories.\n- epic — Golden Epic: Huge skies, golden sunsets and dust in the air. Feels like a movie. Best for history, war and adventure.\nDefault: default.","type":"string","enum":["default","horror","noir","sunny","epic"]},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"additionalProperties":false},"example":{"idea":"You find a bag of money in a stranger's car","flavor":"you-decide","lengthSeconds":"90"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"plan":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}},"required":["id","status"],"additionalProperties":false},"job":{"description":"Follow it with autoclips_jobs get. It succeeds when the plan is ready (result.planId).","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"approvedCredits":{"description":"The planning's spending limit you approved. Charged at cost when the plan is ready, usually less.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["plan","job","approvedCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"plan":{"id":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d","status":"queued"},"job":{"id":"job_66f2a0000000000000000a01","product":"stickman","kind":"stickman.plan","resource":{"type":"plan","id":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d"},"status":"running","step":"Waiting to start","progress":5,"result":null,"error":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","finishedAt":null,"poll_after_seconds":15},"approvedCredits":1200}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"stickman_plans_list","summary":"Your recent Stickman Story plans, newest first.","description":"Your recent Stickman Story plans, newest first.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.plans.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_plans action=list","parameters":[{"name":"limit","in":"query","required":false,"schema":{"description":"How many plans (1 to 20, default 6).","default":6,"type":"integer","minimum":1,"maximum":20},"description":"How many plans (1 to 20, default 6)."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"plans":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"flavor":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","title","flavor","createdAt","updatedAt"],"additionalProperties":false}}},"required":["plans"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"plans":[{"id":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d","status":"plan-ready","title":"The Bag","flavor":"you-decide","createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/plans/{planId}":{"get":{"operationId":"stickman_plans_get","summary":"One plan: its status, the Director's question, the scenes, the vote or ending, facts, cast and what it cost so far.","description":"One plan: its status, the Director's question, the scenes, the vote or ending, facts, cast and what it cost so far.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.plans.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_plans action=get","parameters":[{"name":"planId","in":"path","required":true,"schema":{"description":"The plan (planId from stickman_plans create or list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The plan (planId from stickman_plans create or list).","example":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"plan":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"description":"queued, researching, awaiting_user, casting, plan-ready, started, failed or cancelled.","anyOf":[{"type":"string"},{"type":"null"}]},"lengthSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"story":{"type":"string"},"events":{"type":"array","items":{"type":"object","properties":{"at":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["at","kind","text"],"additionalProperties":false}},"question":{"description":"The Director's question while it waits for your answer (stickman_plans answer).","anyOf":[{"type":"object","properties":{"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"options":{"type":"array","items":{}}},"required":["question","options"],"additionalProperties":false},{"type":"null"}]},"pictures":{"type":"array","items":{"type":"object","properties":{"uploadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"castId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["uploadId","caption","url","kind","castId"],"additionalProperties":false}},"plan":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"hookLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"pov":{"anyOf":[{"type":"string"},{"type":"null"}]},"beats":{"type":"array","items":{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"what":{"anyOf":[{"type":"string"},{"type":"null"}]},"castIds":{"type":"array","items":{"type":"string"}},"card":{"anyOf":[{},{"type":"null"}]},"visual":{"type":"string"},"locationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"timeOfDay":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}}},"required":["n","what","castIds","card","locationId","timeOfDay"],"additionalProperties":false}},"ending":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"a":{"anyOf":[{"type":"string"},{"type":"null"}]},"b":{"anyOf":[{"type":"string"},{"type":"null"}]},"aLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"bLine":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","question","a","b","aLine","bLine"],"additionalProperties":false},{"type":"null"}]},"cards":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},{"type":"null"}]}},"required":["title","logline","hookLine","pov","beats","ending","cards"],"additionalProperties":false},{"type":"null"}]},"facts":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"claim":{"anyOf":[{"type":"string"},{"type":"null"}]},"value":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"date":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceTitle":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","claim","value","unit","date","sourceUrl","sourceTitle"],"additionalProperties":false}},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"isViewer":{"type":"boolean"},"realPerson":{"type":"boolean"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"variants":{"type":"array","items":{"type":"string"}},"pickedVariant":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"looks":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["used","max"],"additionalProperties":false}},"required":["castId","name","role","isViewer","realPerson","status","variants","pickedVariant","looks"],"additionalProperties":false}},"assets":{"type":"array","items":{"type":"object","properties":{"assetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"placement":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["assetId","kind","name","url","placement","status"],"additionalProperties":false}},"places":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","status","masterUrl","posterUrl"],"additionalProperties":false}},"props":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"states":{"type":"array","items":{"type":"string"}},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","states","status","masterUrl","posterUrl"],"additionalProperties":false}},"issues":{"type":"array","items":{}},"error":{"anyOf":[{"type":"object","properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"projectId":{"description":"The video made from this plan, once it is started.","anyOf":[{"type":"string"},{"type":"null"}]},"billing":{"description":"Credits charged so far, and what the plan has cost so far.","type":"object","properties":{"chargedCredits":{"type":"number"},"runningCredits":{"type":"number"}},"required":["chargedCredits","runningCredits"],"additionalProperties":false},"revisions":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"active":{"type":"boolean"},"error":{"anyOf":[{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["n","code","message"],"additionalProperties":false},{"type":"null"}]}},"required":["used","max","active","error"],"additionalProperties":false},"script":{"type":"object","properties":{"lines":{"type":"array","items":{}},"label":{"anyOf":[{"type":"number"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pace":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"vote":{"anyOf":[{"type":"object","properties":{"question":{"type":"string"},"a":{"type":"string"},"b":{"type":"string"}},"required":["a","b"],"additionalProperties":false},{"type":"null"}]},"quote":{}},"required":["lines","label","voiceId","pace","language","vote","quote"],"additionalProperties":false}},"required":["id","status","lengthSeconds","story","events","question","pictures","plan","facts","cast","assets","places","props","issues","error","projectId","billing","revisions"],"additionalProperties":false}},"required":["plan"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"plan":{"id":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d","status":"plan-ready","lengthSeconds":90,"story":"You find a bag of money in a stranger's car","events":[{"at":"2026-10-25T10:00:00.000Z","kind":"status","text":"Plan ready"}],"question":null,"pictures":[],"plan":{"title":"The Bag","logline":"You find a bag of money in a stranger's car, and the stranger is watching.","hookLine":"You were only looking for your phone.","pov":"second","beats":[{"n":1,"what":"You open the wrong car door","castIds":["you"],"card":{"kind":"none","text":""},"locationId":"lot","timeOfDay":"night"}],"ending":{"type":"vote","question":"Keep it?","a":"KEEP","b":"RUN","aLine":"You keep the money.","bLine":"You run."},"cards":{"enabled":true,"theme":"night"}},"facts":[],"cast":[{"castId":"you","name":"You","role":"protagonist","isViewer":true,"realPerson":false,"status":"done","variants":["https://media.autoclips.app/stickman/you.png"],"pickedVariant":0,"looks":{"used":0,"max":5}}],"assets":[],"places":[],"props":[],"issues":[],"error":null,"projectId":null,"billing":{"chargedCredits":640,"runningCredits":640},"revisions":{"used":0,"max":5,"active":false,"error":null}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"stickman_plans_update","summary":"Change a ready plan's words, vote, facts, cast picks or names, swap in a My cast character, or its text cards.","description":"Changes a ready plan without drawing anything: its title, hook line, a scene's line (beatLines, by the scene's number from 0), facts to drop, the vote words, which drawn version each cast member uses, their names, a cast member swapped for a My cast character (castSwap) and the text cards. A True Story's lines may only say numbers its sources give. A script plan keeps its own words: change them with update_script. Paid plans only.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.plans.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_plans action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":60},"hookLine":{"type":"string","minLength":1,"maxLength":120},"beatLines":{"description":"Scene lines by scene number (from 0): { \"2\": \"You open the trunk\" }.","type":"object","propertyNames":{"type":"string","pattern":"^\\d{1,2}$"},"additionalProperties":{"type":"string","minLength":1,"maxLength":240}},"removeFactIds":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":40}},"ending":{"description":"The vote's two words.","type":"object","properties":{"a":{"type":"string","minLength":1,"maxLength":14},"b":{"type":"string","minLength":1,"maxLength":14}},"required":["a","b"],"additionalProperties":false},"castPicks":{"description":"Which drawn version each cast member uses: { castId: version number from 0 }.","type":"object","propertyNames":{"type":"string","maxLength":40},"additionalProperties":{"type":"integer","minimum":0,"maximum":17}},"castNames":{"description":"New names: { castId: name }.","type":"object","propertyNames":{"type":"string","maxLength":40},"additionalProperties":{"type":"string","minLength":1,"maxLength":32}},"castSwap":{"description":"Make a planned cast member a My cast character (or \"preset:<slug>\"). Free: nothing is drawn.","type":"object","properties":{"castId":{"type":"string","maxLength":40},"characterId":{"type":"string","maxLength":80}},"required":["castId","characterId"],"additionalProperties":false},"cards":{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"description":"Text card look: The look of a Story's on-screen text cards and its end card.\nChoices:\n- night — Night: Dark card, green edge.\n- ink — Ink: Dark tiles, pink accents, paper fact cards.\n- clean — Clean: White card, black text.\nDefault: Night for You Decide, Ink for True Story (leave it out).","type":"string","enum":["night","ink","clean"]}},"additionalProperties":false}},"additionalProperties":false},"example":{"title":"The Bag in the Back Seat","ending":{"a":"KEEP","b":"RETURN"}}}}},"parameters":[{"name":"planId","in":"path","required":true,"schema":{"description":"The plan (planId from stickman_plans create or list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The plan (planId from stickman_plans create or list).","example":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"plan":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"description":"queued, researching, awaiting_user, casting, plan-ready, started, failed or cancelled.","anyOf":[{"type":"string"},{"type":"null"}]},"lengthSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"story":{"type":"string"},"events":{"type":"array","items":{"type":"object","properties":{"at":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["at","kind","text"],"additionalProperties":false}},"question":{"description":"The Director's question while it waits for your answer (stickman_plans answer).","anyOf":[{"type":"object","properties":{"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"options":{"type":"array","items":{}}},"required":["question","options"],"additionalProperties":false},{"type":"null"}]},"pictures":{"type":"array","items":{"type":"object","properties":{"uploadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"castId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["uploadId","caption","url","kind","castId"],"additionalProperties":false}},"plan":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"hookLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"pov":{"anyOf":[{"type":"string"},{"type":"null"}]},"beats":{"type":"array","items":{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"what":{"anyOf":[{"type":"string"},{"type":"null"}]},"castIds":{"type":"array","items":{"type":"string"}},"card":{"anyOf":[{},{"type":"null"}]},"visual":{"type":"string"},"locationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"timeOfDay":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}}},"required":["n","what","castIds","card","locationId","timeOfDay"],"additionalProperties":false}},"ending":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"a":{"anyOf":[{"type":"string"},{"type":"null"}]},"b":{"anyOf":[{"type":"string"},{"type":"null"}]},"aLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"bLine":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","question","a","b","aLine","bLine"],"additionalProperties":false},{"type":"null"}]},"cards":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},{"type":"null"}]}},"required":["title","logline","hookLine","pov","beats","ending","cards"],"additionalProperties":false},{"type":"null"}]},"facts":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"claim":{"anyOf":[{"type":"string"},{"type":"null"}]},"value":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"date":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceTitle":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","claim","value","unit","date","sourceUrl","sourceTitle"],"additionalProperties":false}},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"isViewer":{"type":"boolean"},"realPerson":{"type":"boolean"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"variants":{"type":"array","items":{"type":"string"}},"pickedVariant":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"looks":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["used","max"],"additionalProperties":false}},"required":["castId","name","role","isViewer","realPerson","status","variants","pickedVariant","looks"],"additionalProperties":false}},"assets":{"type":"array","items":{"type":"object","properties":{"assetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"placement":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["assetId","kind","name","url","placement","status"],"additionalProperties":false}},"places":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","status","masterUrl","posterUrl"],"additionalProperties":false}},"props":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"states":{"type":"array","items":{"type":"string"}},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","states","status","masterUrl","posterUrl"],"additionalProperties":false}},"issues":{"type":"array","items":{}},"error":{"anyOf":[{"type":"object","properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"projectId":{"description":"The video made from this plan, once it is started.","anyOf":[{"type":"string"},{"type":"null"}]},"billing":{"description":"Credits charged so far, and what the plan has cost so far.","type":"object","properties":{"chargedCredits":{"type":"number"},"runningCredits":{"type":"number"}},"required":["chargedCredits","runningCredits"],"additionalProperties":false},"revisions":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"active":{"type":"boolean"},"error":{"anyOf":[{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["n","code","message"],"additionalProperties":false},{"type":"null"}]}},"required":["used","max","active","error"],"additionalProperties":false},"script":{"type":"object","properties":{"lines":{"type":"array","items":{}},"label":{"anyOf":[{"type":"number"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pace":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"vote":{"anyOf":[{"type":"object","properties":{"question":{"type":"string"},"a":{"type":"string"},"b":{"type":"string"}},"required":["a","b"],"additionalProperties":false},{"type":"null"}]},"quote":{}},"required":["lines","label","voiceId","pace","language","vote","quote"],"additionalProperties":false}},"required":["id","status","lengthSeconds","story","events","question","pictures","plan","facts","cast","assets","places","props","issues","error","projectId","billing","revisions"],"additionalProperties":false}},"required":["plan"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"plan":{"id":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d","status":"plan-ready","lengthSeconds":90,"story":"You find a bag of money in a stranger's car","events":[{"at":"2026-10-25T10:00:00.000Z","kind":"status","text":"Plan ready"}],"question":null,"pictures":[],"plan":{"title":"The Bag","logline":"You find a bag of money in a stranger's car, and the stranger is watching.","hookLine":"You were only looking for your phone.","pov":"second","beats":[{"n":1,"what":"You open the wrong car door","castIds":["you"],"card":{"kind":"none","text":""},"locationId":"lot","timeOfDay":"night"}],"ending":{"type":"vote","question":"Keep it?","a":"KEEP","b":"RUN","aLine":"You keep the money.","bLine":"You run."},"cards":{"enabled":true,"theme":"night"}},"facts":[],"cast":[{"castId":"you","name":"You","role":"protagonist","isViewer":true,"realPerson":false,"status":"done","variants":["https://media.autoclips.app/stickman/you.png"],"pickedVariant":0,"looks":{"used":0,"max":5}}],"assets":[],"places":[],"props":[],"issues":[],"error":null,"projectId":null,"billing":{"chargedCredits":640,"runningCredits":640},"revisions":{"used":0,"max":5,"active":false,"error":null}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/plans/{planId}/answer":{"post":{"operationId":"stickman_plans_answer","summary":"Answer the Director's question, so the plan goes on.","description":"Sends your answer to the one question the Director asked (the plan's question). The research goes on under the spending limit approved with create.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.plans.answer","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_plans action=answer","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"answer":{"description":"Your answer, 1 to 300 characters.","type":"string","minLength":1,"maxLength":300}},"required":["answer"],"additionalProperties":false},"example":{"answer":"Keep it set in the 1960s."}}}},"parameters":[{"name":"planId","in":"path","required":true,"schema":{"description":"The plan (planId from stickman_plans create or list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The plan (planId from stickman_plans create or list).","example":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"plan":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"description":"queued, researching, awaiting_user, casting, plan-ready, started, failed or cancelled.","anyOf":[{"type":"string"},{"type":"null"}]},"lengthSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"story":{"type":"string"},"events":{"type":"array","items":{"type":"object","properties":{"at":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["at","kind","text"],"additionalProperties":false}},"question":{"description":"The Director's question while it waits for your answer (stickman_plans answer).","anyOf":[{"type":"object","properties":{"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"options":{"type":"array","items":{}}},"required":["question","options"],"additionalProperties":false},{"type":"null"}]},"pictures":{"type":"array","items":{"type":"object","properties":{"uploadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"castId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["uploadId","caption","url","kind","castId"],"additionalProperties":false}},"plan":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"hookLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"pov":{"anyOf":[{"type":"string"},{"type":"null"}]},"beats":{"type":"array","items":{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"what":{"anyOf":[{"type":"string"},{"type":"null"}]},"castIds":{"type":"array","items":{"type":"string"}},"card":{"anyOf":[{},{"type":"null"}]},"visual":{"type":"string"},"locationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"timeOfDay":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}}},"required":["n","what","castIds","card","locationId","timeOfDay"],"additionalProperties":false}},"ending":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"a":{"anyOf":[{"type":"string"},{"type":"null"}]},"b":{"anyOf":[{"type":"string"},{"type":"null"}]},"aLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"bLine":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","question","a","b","aLine","bLine"],"additionalProperties":false},{"type":"null"}]},"cards":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},{"type":"null"}]}},"required":["title","logline","hookLine","pov","beats","ending","cards"],"additionalProperties":false},{"type":"null"}]},"facts":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"claim":{"anyOf":[{"type":"string"},{"type":"null"}]},"value":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"date":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceTitle":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","claim","value","unit","date","sourceUrl","sourceTitle"],"additionalProperties":false}},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"isViewer":{"type":"boolean"},"realPerson":{"type":"boolean"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"variants":{"type":"array","items":{"type":"string"}},"pickedVariant":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"looks":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["used","max"],"additionalProperties":false}},"required":["castId","name","role","isViewer","realPerson","status","variants","pickedVariant","looks"],"additionalProperties":false}},"assets":{"type":"array","items":{"type":"object","properties":{"assetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"placement":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["assetId","kind","name","url","placement","status"],"additionalProperties":false}},"places":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","status","masterUrl","posterUrl"],"additionalProperties":false}},"props":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"states":{"type":"array","items":{"type":"string"}},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","states","status","masterUrl","posterUrl"],"additionalProperties":false}},"issues":{"type":"array","items":{}},"error":{"anyOf":[{"type":"object","properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"projectId":{"description":"The video made from this plan, once it is started.","anyOf":[{"type":"string"},{"type":"null"}]},"billing":{"description":"Credits charged so far, and what the plan has cost so far.","type":"object","properties":{"chargedCredits":{"type":"number"},"runningCredits":{"type":"number"}},"required":["chargedCredits","runningCredits"],"additionalProperties":false},"revisions":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"active":{"type":"boolean"},"error":{"anyOf":[{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["n","code","message"],"additionalProperties":false},{"type":"null"}]}},"required":["used","max","active","error"],"additionalProperties":false},"script":{"type":"object","properties":{"lines":{"type":"array","items":{}},"label":{"anyOf":[{"type":"number"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pace":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"vote":{"anyOf":[{"type":"object","properties":{"question":{"type":"string"},"a":{"type":"string"},"b":{"type":"string"}},"required":["a","b"],"additionalProperties":false},{"type":"null"}]},"quote":{}},"required":["lines","label","voiceId","pace","language","vote","quote"],"additionalProperties":false}},"required":["id","status","lengthSeconds","story","events","question","pictures","plan","facts","cast","assets","places","props","issues","error","projectId","billing","revisions"],"additionalProperties":false}},"required":["plan"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"plan":{"id":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d","status":"researching","lengthSeconds":90,"story":"You find a bag of money in a stranger's car","events":[{"at":"2026-10-25T10:00:00.000Z","kind":"status","text":"Plan ready"}],"question":null,"pictures":[],"plan":{"title":"The Bag","logline":"You find a bag of money in a stranger's car, and the stranger is watching.","hookLine":"You were only looking for your phone.","pov":"second","beats":[{"n":1,"what":"You open the wrong car door","castIds":["you"],"card":{"kind":"none","text":""},"locationId":"lot","timeOfDay":"night"}],"ending":{"type":"vote","question":"Keep it?","a":"KEEP","b":"RUN","aLine":"You keep the money.","bLine":"You run."},"cards":{"enabled":true,"theme":"night"}},"facts":[],"cast":[{"castId":"you","name":"You","role":"protagonist","isViewer":true,"realPerson":false,"status":"done","variants":["https://media.autoclips.app/stickman/you.png"],"pickedVariant":0,"looks":{"used":0,"max":5}}],"assets":[],"places":[],"props":[],"issues":[],"error":null,"projectId":null,"billing":{"chargedCredits":640,"runningCredits":640},"revisions":{"used":0,"max":5,"active":false,"error":null}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/plans/{planId}/cancel":{"post":{"operationId":"stickman_plans_cancel","summary":"Stop planning. Research already done is charged at cost.","description":"Stops a plan. A plan stopped while it researches, waits for your answer or draws its cast is charged what it really spent, at cost, never above its cap (the price shown is that cap less what was charged before). A plan that is ready was charged when it got there, so stopping it charges nothing more; a plan approved through the API is covered by that approval. A plan made into a video cannot be stopped.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.plans.cancel","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_plans action=cancel","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"planId","in":"path","required":true,"schema":{"description":"The plan (planId from stickman_plans create or list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The plan (planId from stickman_plans create or list).","example":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"plan":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"description":"queued, researching, awaiting_user, casting, plan-ready, started, failed or cancelled.","anyOf":[{"type":"string"},{"type":"null"}]},"lengthSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"story":{"type":"string"},"events":{"type":"array","items":{"type":"object","properties":{"at":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["at","kind","text"],"additionalProperties":false}},"question":{"description":"The Director's question while it waits for your answer (stickman_plans answer).","anyOf":[{"type":"object","properties":{"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"options":{"type":"array","items":{}}},"required":["question","options"],"additionalProperties":false},{"type":"null"}]},"pictures":{"type":"array","items":{"type":"object","properties":{"uploadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"castId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["uploadId","caption","url","kind","castId"],"additionalProperties":false}},"plan":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"hookLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"pov":{"anyOf":[{"type":"string"},{"type":"null"}]},"beats":{"type":"array","items":{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"what":{"anyOf":[{"type":"string"},{"type":"null"}]},"castIds":{"type":"array","items":{"type":"string"}},"card":{"anyOf":[{},{"type":"null"}]},"visual":{"type":"string"},"locationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"timeOfDay":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}}},"required":["n","what","castIds","card","locationId","timeOfDay"],"additionalProperties":false}},"ending":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"a":{"anyOf":[{"type":"string"},{"type":"null"}]},"b":{"anyOf":[{"type":"string"},{"type":"null"}]},"aLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"bLine":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","question","a","b","aLine","bLine"],"additionalProperties":false},{"type":"null"}]},"cards":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},{"type":"null"}]}},"required":["title","logline","hookLine","pov","beats","ending","cards"],"additionalProperties":false},{"type":"null"}]},"facts":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"claim":{"anyOf":[{"type":"string"},{"type":"null"}]},"value":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"date":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceTitle":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","claim","value","unit","date","sourceUrl","sourceTitle"],"additionalProperties":false}},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"isViewer":{"type":"boolean"},"realPerson":{"type":"boolean"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"variants":{"type":"array","items":{"type":"string"}},"pickedVariant":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"looks":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["used","max"],"additionalProperties":false}},"required":["castId","name","role","isViewer","realPerson","status","variants","pickedVariant","looks"],"additionalProperties":false}},"assets":{"type":"array","items":{"type":"object","properties":{"assetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"placement":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["assetId","kind","name","url","placement","status"],"additionalProperties":false}},"places":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","status","masterUrl","posterUrl"],"additionalProperties":false}},"props":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"states":{"type":"array","items":{"type":"string"}},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","states","status","masterUrl","posterUrl"],"additionalProperties":false}},"issues":{"type":"array","items":{}},"error":{"anyOf":[{"type":"object","properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"projectId":{"description":"The video made from this plan, once it is started.","anyOf":[{"type":"string"},{"type":"null"}]},"billing":{"description":"Credits charged so far, and what the plan has cost so far.","type":"object","properties":{"chargedCredits":{"type":"number"},"runningCredits":{"type":"number"}},"required":["chargedCredits","runningCredits"],"additionalProperties":false},"revisions":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"active":{"type":"boolean"},"error":{"anyOf":[{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["n","code","message"],"additionalProperties":false},{"type":"null"}]}},"required":["used","max","active","error"],"additionalProperties":false},"script":{"type":"object","properties":{"lines":{"type":"array","items":{}},"label":{"anyOf":[{"type":"number"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pace":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"vote":{"anyOf":[{"type":"object","properties":{"question":{"type":"string"},"a":{"type":"string"},"b":{"type":"string"}},"required":["a","b"],"additionalProperties":false},{"type":"null"}]},"quote":{}},"required":["lines","label","voiceId","pace","language","vote","quote"],"additionalProperties":false}},"required":["id","status","lengthSeconds","story","events","question","pictures","plan","facts","cast","assets","places","props","issues","error","projectId","billing","revisions"],"additionalProperties":false},"charged":{"description":"Credits this stop charged.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["plan","charged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"plan":{"id":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d","status":"cancelled","lengthSeconds":90,"story":"You find a bag of money in a stranger's car","events":[{"at":"2026-10-25T10:00:00.000Z","kind":"status","text":"Plan ready"}],"question":null,"pictures":[],"plan":null,"facts":[],"cast":[{"castId":"you","name":"You","role":"protagonist","isViewer":true,"realPerson":false,"status":"done","variants":["https://media.autoclips.app/stickman/you.png"],"pickedVariant":0,"looks":{"used":0,"max":5}}],"assets":[],"places":[],"props":[],"issues":[],"error":null,"projectId":null,"billing":{"chargedCredits":240,"runningCredits":240},"revisions":{"used":0,"max":5,"active":false,"error":null}},"charged":240}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/plans/{planId}/cast":{"post":{"operationId":"stickman_plans_add_cast","summary":"Add a My cast character to a ready plan, in a role you name. What you approve is the change's spending limit.","description":"The character joins the story through a change to the plan (the Director plans them in), billed like any change: at cost when the plan is ready again, never above the limit you approve (the most the run can be charged). A story has at most 6 characters.\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. The limit is the most Stickman Story plan can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.plans.add_cast","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_plans action=add_cast","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"characterId":{"description":"A My cast id (stickman_cast list) or \"preset:<slug>\".","type":"string","minLength":1,"maxLength":80},"role":{"description":"Who they are in the story, 1 to 60 characters.","type":"string","minLength":1,"maxLength":60},"changeLimit":{"description":"This change's spending limit, 300 to 2,400 credits (default 1,200).","type":"integer","minimum":300,"maximum":2400},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["characterId","role"],"additionalProperties":false},"example":{"characterId":"preset:maya","role":"the detective following you"}}}},"parameters":[{"name":"planId","in":"path","required":true,"schema":{"description":"The plan (planId from stickman_plans create or list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The plan (planId from stickman_plans create or list).","example":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"plan":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"description":"queued, researching, awaiting_user, casting, plan-ready, started, failed or cancelled.","anyOf":[{"type":"string"},{"type":"null"}]},"lengthSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"story":{"type":"string"},"events":{"type":"array","items":{"type":"object","properties":{"at":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["at","kind","text"],"additionalProperties":false}},"question":{"description":"The Director's question while it waits for your answer (stickman_plans answer).","anyOf":[{"type":"object","properties":{"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"options":{"type":"array","items":{}}},"required":["question","options"],"additionalProperties":false},{"type":"null"}]},"pictures":{"type":"array","items":{"type":"object","properties":{"uploadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"castId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["uploadId","caption","url","kind","castId"],"additionalProperties":false}},"plan":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"hookLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"pov":{"anyOf":[{"type":"string"},{"type":"null"}]},"beats":{"type":"array","items":{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"what":{"anyOf":[{"type":"string"},{"type":"null"}]},"castIds":{"type":"array","items":{"type":"string"}},"card":{"anyOf":[{},{"type":"null"}]},"visual":{"type":"string"},"locationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"timeOfDay":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}}},"required":["n","what","castIds","card","locationId","timeOfDay"],"additionalProperties":false}},"ending":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"a":{"anyOf":[{"type":"string"},{"type":"null"}]},"b":{"anyOf":[{"type":"string"},{"type":"null"}]},"aLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"bLine":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","question","a","b","aLine","bLine"],"additionalProperties":false},{"type":"null"}]},"cards":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},{"type":"null"}]}},"required":["title","logline","hookLine","pov","beats","ending","cards"],"additionalProperties":false},{"type":"null"}]},"facts":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"claim":{"anyOf":[{"type":"string"},{"type":"null"}]},"value":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"date":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceTitle":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","claim","value","unit","date","sourceUrl","sourceTitle"],"additionalProperties":false}},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"isViewer":{"type":"boolean"},"realPerson":{"type":"boolean"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"variants":{"type":"array","items":{"type":"string"}},"pickedVariant":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"looks":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["used","max"],"additionalProperties":false}},"required":["castId","name","role","isViewer","realPerson","status","variants","pickedVariant","looks"],"additionalProperties":false}},"assets":{"type":"array","items":{"type":"object","properties":{"assetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"placement":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["assetId","kind","name","url","placement","status"],"additionalProperties":false}},"places":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","status","masterUrl","posterUrl"],"additionalProperties":false}},"props":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"states":{"type":"array","items":{"type":"string"}},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","states","status","masterUrl","posterUrl"],"additionalProperties":false}},"issues":{"type":"array","items":{}},"error":{"anyOf":[{"type":"object","properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"projectId":{"description":"The video made from this plan, once it is started.","anyOf":[{"type":"string"},{"type":"null"}]},"billing":{"description":"Credits charged so far, and what the plan has cost so far.","type":"object","properties":{"chargedCredits":{"type":"number"},"runningCredits":{"type":"number"}},"required":["chargedCredits","runningCredits"],"additionalProperties":false},"revisions":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"active":{"type":"boolean"},"error":{"anyOf":[{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["n","code","message"],"additionalProperties":false},{"type":"null"}]}},"required":["used","max","active","error"],"additionalProperties":false},"script":{"type":"object","properties":{"lines":{"type":"array","items":{}},"label":{"anyOf":[{"type":"number"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pace":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"vote":{"anyOf":[{"type":"object","properties":{"question":{"type":"string"},"a":{"type":"string"},"b":{"type":"string"}},"required":["a","b"],"additionalProperties":false},{"type":"null"}]},"quote":{}},"required":["lines","label","voiceId","pace","language","vote","quote"],"additionalProperties":false}},"required":["id","status","lengthSeconds","story","events","question","pictures","plan","facts","cast","assets","places","props","issues","error","projectId","billing","revisions"],"additionalProperties":false},"job":{"description":"Follow the change with autoclips_jobs get. Null when nothing needed drawing.","anyOf":[{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},{"type":"null"}]},"approvedCredits":{"description":"The spending limit you approved for this change. It is charged at cost when the plan is ready again, usually less.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["plan","job","approvedCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/plans/{planId}/cast/{castId}/looks":{"post":{"operationId":"stickman_plans_cast_look","summary":"A new look for one cast member of a ready plan: draw again, from a photo, or with a change you describe.","description":"look: regenerate (new versions of the same look), photo (drawn from a picture you added with stickman_story upload_image: uploadId) or edit (the same picture with one change you describe: change). The pictures are charged at what they really cost when they are ready, never above the limit you approve (the most the run can be charged); when nothing can be drawn the old look stays and nothing is charged. 5 new looks per cast member.\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. The limit is the most Stickman Story plan can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.plans.cast_look","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_plans action=cast_look","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"look":{"description":"Cast look change: How a plan's cast member gets a new look. Charged at what the pictures really cost.\nChoices:\n- regenerate — New look: Draws the cast member again from their description. (Draws up to 3 pictures, charged at cost)\n- photo — From a photo: Draws the cast member from a photo of a real adult you add. (Draws up to 3 pictures, charged at cost)\n- edit — Change the look: Keeps the cast member and changes what you ask (clothes, hair, glasses). (Draws up to 2 pictures, charged at cost)\nNo default: ask the user.","type":"string","enum":["regenerate","photo","edit"]},"uploadId":{"description":"look photo: the picture to draw them from.","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"change":{"description":"look edit: the change, 3 to 120 characters.","type":"string","minLength":3,"maxLength":120},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["look"],"additionalProperties":false},"example":{"look":"regenerate"}}}},"parameters":[{"name":"planId","in":"path","required":true,"schema":{"description":"The plan (planId from stickman_plans create or list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The plan (planId from stickman_plans create or list).","example":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d"},{"name":"castId","in":"path","required":true,"schema":{"description":"The cast member (cast[].castId of the plan).","type":"string","minLength":1,"maxLength":40},"description":"The cast member (cast[].castId of the plan).","example":"stranger"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"plan":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"description":"queued, researching, awaiting_user, casting, plan-ready, started, failed or cancelled.","anyOf":[{"type":"string"},{"type":"null"}]},"lengthSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"story":{"type":"string"},"events":{"type":"array","items":{"type":"object","properties":{"at":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["at","kind","text"],"additionalProperties":false}},"question":{"description":"The Director's question while it waits for your answer (stickman_plans answer).","anyOf":[{"type":"object","properties":{"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"options":{"type":"array","items":{}}},"required":["question","options"],"additionalProperties":false},{"type":"null"}]},"pictures":{"type":"array","items":{"type":"object","properties":{"uploadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"castId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["uploadId","caption","url","kind","castId"],"additionalProperties":false}},"plan":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"hookLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"pov":{"anyOf":[{"type":"string"},{"type":"null"}]},"beats":{"type":"array","items":{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"what":{"anyOf":[{"type":"string"},{"type":"null"}]},"castIds":{"type":"array","items":{"type":"string"}},"card":{"anyOf":[{},{"type":"null"}]},"visual":{"type":"string"},"locationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"timeOfDay":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}}},"required":["n","what","castIds","card","locationId","timeOfDay"],"additionalProperties":false}},"ending":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"a":{"anyOf":[{"type":"string"},{"type":"null"}]},"b":{"anyOf":[{"type":"string"},{"type":"null"}]},"aLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"bLine":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","question","a","b","aLine","bLine"],"additionalProperties":false},{"type":"null"}]},"cards":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},{"type":"null"}]}},"required":["title","logline","hookLine","pov","beats","ending","cards"],"additionalProperties":false},{"type":"null"}]},"facts":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"claim":{"anyOf":[{"type":"string"},{"type":"null"}]},"value":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"date":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceTitle":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","claim","value","unit","date","sourceUrl","sourceTitle"],"additionalProperties":false}},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"isViewer":{"type":"boolean"},"realPerson":{"type":"boolean"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"variants":{"type":"array","items":{"type":"string"}},"pickedVariant":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"looks":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["used","max"],"additionalProperties":false}},"required":["castId","name","role","isViewer","realPerson","status","variants","pickedVariant","looks"],"additionalProperties":false}},"assets":{"type":"array","items":{"type":"object","properties":{"assetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"placement":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["assetId","kind","name","url","placement","status"],"additionalProperties":false}},"places":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","status","masterUrl","posterUrl"],"additionalProperties":false}},"props":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"states":{"type":"array","items":{"type":"string"}},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","states","status","masterUrl","posterUrl"],"additionalProperties":false}},"issues":{"type":"array","items":{}},"error":{"anyOf":[{"type":"object","properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"projectId":{"description":"The video made from this plan, once it is started.","anyOf":[{"type":"string"},{"type":"null"}]},"billing":{"description":"Credits charged so far, and what the plan has cost so far.","type":"object","properties":{"chargedCredits":{"type":"number"},"runningCredits":{"type":"number"}},"required":["chargedCredits","runningCredits"],"additionalProperties":false},"revisions":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"active":{"type":"boolean"},"error":{"anyOf":[{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["n","code","message"],"additionalProperties":false},{"type":"null"}]}},"required":["used","max","active","error"],"additionalProperties":false},"script":{"type":"object","properties":{"lines":{"type":"array","items":{}},"label":{"anyOf":[{"type":"number"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pace":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"vote":{"anyOf":[{"type":"object","properties":{"question":{"type":"string"},"a":{"type":"string"},"b":{"type":"string"}},"required":["a","b"],"additionalProperties":false},{"type":"null"}]},"quote":{}},"required":["lines","label","voiceId","pace","language","vote","quote"],"additionalProperties":false}},"required":["id","status","lengthSeconds","story","events","question","pictures","plan","facts","cast","assets","places","props","issues","error","projectId","billing","revisions"],"additionalProperties":false},"job":{"description":"Follow the change with autoclips_jobs get. Null when nothing needed drawing.","anyOf":[{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},{"type":"null"}]},"approvedCredits":{"description":"The spending limit you approved for this change. It is charged at cost when the plan is ready again, usually less.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["plan","job","approvedCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/plans/{planId}/photos":{"post":{"operationId":"stickman_plans_rebind_photos","summary":"Say whose photo draws whom in a ready plan (\"Someone else?\"). What you approve is the spending limit of the redraw.","description":"bindings maps each person picture of the plan (its imageId) to the cast member it shows (castId), or null for nobody. The members a picture leaves or joins are drawn again, charged at what the pictures really cost when they are ready, never above the limit you approve (the most the run can be charged). A binding that changes nothing draws nothing.\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. The limit is the most Stickman Story plan can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.plans.rebind_photos","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_plans action=rebind_photos","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bindings":{"description":"{ imageId: castId or null }, 1 to 8 pictures.","type":"object","propertyNames":{"type":"string","maxLength":40},"additionalProperties":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]}},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["bindings"],"additionalProperties":false},"example":{"bindings":{"img2":"stranger"}}}}},"parameters":[{"name":"planId","in":"path","required":true,"schema":{"description":"The plan (planId from stickman_plans create or list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The plan (planId from stickman_plans create or list).","example":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"plan":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"description":"queued, researching, awaiting_user, casting, plan-ready, started, failed or cancelled.","anyOf":[{"type":"string"},{"type":"null"}]},"lengthSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"story":{"type":"string"},"events":{"type":"array","items":{"type":"object","properties":{"at":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["at","kind","text"],"additionalProperties":false}},"question":{"description":"The Director's question while it waits for your answer (stickman_plans answer).","anyOf":[{"type":"object","properties":{"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"options":{"type":"array","items":{}}},"required":["question","options"],"additionalProperties":false},{"type":"null"}]},"pictures":{"type":"array","items":{"type":"object","properties":{"uploadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"castId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["uploadId","caption","url","kind","castId"],"additionalProperties":false}},"plan":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"hookLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"pov":{"anyOf":[{"type":"string"},{"type":"null"}]},"beats":{"type":"array","items":{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"what":{"anyOf":[{"type":"string"},{"type":"null"}]},"castIds":{"type":"array","items":{"type":"string"}},"card":{"anyOf":[{},{"type":"null"}]},"visual":{"type":"string"},"locationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"timeOfDay":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}}},"required":["n","what","castIds","card","locationId","timeOfDay"],"additionalProperties":false}},"ending":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"a":{"anyOf":[{"type":"string"},{"type":"null"}]},"b":{"anyOf":[{"type":"string"},{"type":"null"}]},"aLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"bLine":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","question","a","b","aLine","bLine"],"additionalProperties":false},{"type":"null"}]},"cards":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},{"type":"null"}]}},"required":["title","logline","hookLine","pov","beats","ending","cards"],"additionalProperties":false},{"type":"null"}]},"facts":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"claim":{"anyOf":[{"type":"string"},{"type":"null"}]},"value":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"date":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceTitle":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","claim","value","unit","date","sourceUrl","sourceTitle"],"additionalProperties":false}},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"isViewer":{"type":"boolean"},"realPerson":{"type":"boolean"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"variants":{"type":"array","items":{"type":"string"}},"pickedVariant":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"looks":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["used","max"],"additionalProperties":false}},"required":["castId","name","role","isViewer","realPerson","status","variants","pickedVariant","looks"],"additionalProperties":false}},"assets":{"type":"array","items":{"type":"object","properties":{"assetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"placement":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["assetId","kind","name","url","placement","status"],"additionalProperties":false}},"places":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","status","masterUrl","posterUrl"],"additionalProperties":false}},"props":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"states":{"type":"array","items":{"type":"string"}},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","states","status","masterUrl","posterUrl"],"additionalProperties":false}},"issues":{"type":"array","items":{}},"error":{"anyOf":[{"type":"object","properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"projectId":{"description":"The video made from this plan, once it is started.","anyOf":[{"type":"string"},{"type":"null"}]},"billing":{"description":"Credits charged so far, and what the plan has cost so far.","type":"object","properties":{"chargedCredits":{"type":"number"},"runningCredits":{"type":"number"}},"required":["chargedCredits","runningCredits"],"additionalProperties":false},"revisions":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"active":{"type":"boolean"},"error":{"anyOf":[{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["n","code","message"],"additionalProperties":false},{"type":"null"}]}},"required":["used","max","active","error"],"additionalProperties":false},"script":{"type":"object","properties":{"lines":{"type":"array","items":{}},"label":{"anyOf":[{"type":"number"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pace":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"vote":{"anyOf":[{"type":"object","properties":{"question":{"type":"string"},"a":{"type":"string"},"b":{"type":"string"}},"required":["a","b"],"additionalProperties":false},{"type":"null"}]},"quote":{}},"required":["lines","label","voiceId","pace","language","vote","quote"],"additionalProperties":false}},"required":["id","status","lengthSeconds","story","events","question","pictures","plan","facts","cast","assets","places","props","issues","error","projectId","billing","revisions"],"additionalProperties":false},"job":{"description":"Follow the change with autoclips_jobs get. Null when nothing needed drawing.","anyOf":[{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},{"type":"null"}]},"approvedCredits":{"description":"The spending limit you approved for this change. It is charged at cost when the plan is ready again, usually less.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["plan","job","approvedCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/plans/{planId}/revise":{"post":{"operationId":"stickman_plans_revise","summary":"Ask the Director for a change to a ready plan, in your words. What you approve is the change's spending limit.","description":"Sends your change request to the Director, who researches and plans again from the ready plan (up to 5 changes a plan). It is charged at what it really cost when the plan is ready again, never above the limit you approve (the most the run can be charged); a change that fails leaves the plan as it was and is not charged. It answers with a job (status 202).\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. The limit is the most Stickman Story plan can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.plans.revise","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_plans action=revise","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request":{"description":"What to change, 1 to 300 characters.","type":"string","minLength":1,"maxLength":300},"changeLimit":{"description":"This change's spending limit, 300 to 2,400 credits (default 1,200).","type":"integer","minimum":300,"maximum":2400},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["request"],"additionalProperties":false},"example":{"request":"Make the stranger a detective who has been following you."}}}},"parameters":[{"name":"planId","in":"path","required":true,"schema":{"description":"The plan (planId from stickman_plans create or list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The plan (planId from stickman_plans create or list).","example":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"plan":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"description":"queued, researching, awaiting_user, casting, plan-ready, started, failed or cancelled.","anyOf":[{"type":"string"},{"type":"null"}]},"lengthSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"story":{"type":"string"},"events":{"type":"array","items":{"type":"object","properties":{"at":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["at","kind","text"],"additionalProperties":false}},"question":{"description":"The Director's question while it waits for your answer (stickman_plans answer).","anyOf":[{"type":"object","properties":{"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"options":{"type":"array","items":{}}},"required":["question","options"],"additionalProperties":false},{"type":"null"}]},"pictures":{"type":"array","items":{"type":"object","properties":{"uploadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"castId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["uploadId","caption","url","kind","castId"],"additionalProperties":false}},"plan":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"hookLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"pov":{"anyOf":[{"type":"string"},{"type":"null"}]},"beats":{"type":"array","items":{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"what":{"anyOf":[{"type":"string"},{"type":"null"}]},"castIds":{"type":"array","items":{"type":"string"}},"card":{"anyOf":[{},{"type":"null"}]},"visual":{"type":"string"},"locationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"timeOfDay":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}}},"required":["n","what","castIds","card","locationId","timeOfDay"],"additionalProperties":false}},"ending":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"a":{"anyOf":[{"type":"string"},{"type":"null"}]},"b":{"anyOf":[{"type":"string"},{"type":"null"}]},"aLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"bLine":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","question","a","b","aLine","bLine"],"additionalProperties":false},{"type":"null"}]},"cards":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},{"type":"null"}]}},"required":["title","logline","hookLine","pov","beats","ending","cards"],"additionalProperties":false},{"type":"null"}]},"facts":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"claim":{"anyOf":[{"type":"string"},{"type":"null"}]},"value":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"date":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceTitle":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","claim","value","unit","date","sourceUrl","sourceTitle"],"additionalProperties":false}},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"isViewer":{"type":"boolean"},"realPerson":{"type":"boolean"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"variants":{"type":"array","items":{"type":"string"}},"pickedVariant":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"looks":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["used","max"],"additionalProperties":false}},"required":["castId","name","role","isViewer","realPerson","status","variants","pickedVariant","looks"],"additionalProperties":false}},"assets":{"type":"array","items":{"type":"object","properties":{"assetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"placement":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["assetId","kind","name","url","placement","status"],"additionalProperties":false}},"places":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","status","masterUrl","posterUrl"],"additionalProperties":false}},"props":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"states":{"type":"array","items":{"type":"string"}},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","states","status","masterUrl","posterUrl"],"additionalProperties":false}},"issues":{"type":"array","items":{}},"error":{"anyOf":[{"type":"object","properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"projectId":{"description":"The video made from this plan, once it is started.","anyOf":[{"type":"string"},{"type":"null"}]},"billing":{"description":"Credits charged so far, and what the plan has cost so far.","type":"object","properties":{"chargedCredits":{"type":"number"},"runningCredits":{"type":"number"}},"required":["chargedCredits","runningCredits"],"additionalProperties":false},"revisions":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"active":{"type":"boolean"},"error":{"anyOf":[{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["n","code","message"],"additionalProperties":false},{"type":"null"}]}},"required":["used","max","active","error"],"additionalProperties":false},"script":{"type":"object","properties":{"lines":{"type":"array","items":{}},"label":{"anyOf":[{"type":"number"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pace":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"vote":{"anyOf":[{"type":"object","properties":{"question":{"type":"string"},"a":{"type":"string"},"b":{"type":"string"}},"required":["a","b"],"additionalProperties":false},{"type":"null"}]},"quote":{}},"required":["lines","label","voiceId","pace","language","vote","quote"],"additionalProperties":false}},"required":["id","status","lengthSeconds","story","events","question","pictures","plan","facts","cast","assets","places","props","issues","error","projectId","billing","revisions"],"additionalProperties":false},"job":{"description":"Follow the change with autoclips_jobs get. Null when nothing needed drawing.","anyOf":[{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},{"type":"null"}]},"approvedCredits":{"description":"The spending limit you approved for this change. It is charged at cost when the plan is ready again, usually less.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["plan","job","approvedCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"plan":{"id":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d","status":"researching","lengthSeconds":90,"story":"You find a bag of money in a stranger's car","events":[{"at":"2026-10-25T10:00:00.000Z","kind":"status","text":"Plan ready"}],"question":null,"pictures":[],"plan":{"title":"The Bag","logline":"You find a bag of money in a stranger's car, and the stranger is watching.","hookLine":"You were only looking for your phone.","pov":"second","beats":[{"n":1,"what":"You open the wrong car door","castIds":["you"],"card":{"kind":"none","text":""},"locationId":"lot","timeOfDay":"night"}],"ending":{"type":"vote","question":"Keep it?","a":"KEEP","b":"RUN","aLine":"You keep the money.","bLine":"You run."},"cards":{"enabled":true,"theme":"night"}},"facts":[],"cast":[{"castId":"you","name":"You","role":"protagonist","isViewer":true,"realPerson":false,"status":"done","variants":["https://media.autoclips.app/stickman/you.png"],"pickedVariant":0,"looks":{"used":0,"max":5}}],"assets":[],"places":[],"props":[],"issues":[],"error":null,"projectId":null,"billing":{"chargedCredits":640,"runningCredits":640},"revisions":{"used":1,"max":5,"active":true,"error":null}},"job":{"id":"job_66f2a0000000000000000a01","product":"stickman","kind":"stickman.plan","resource":{"type":"plan","id":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d"},"status":"running","step":"Waiting to start","progress":35,"result":null,"error":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","finishedAt":null,"poll_after_seconds":15},"approvedCredits":1200}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/plans/{planId}/script":{"patch":{"operationId":"stickman_plans_update_script","summary":"Change a My script plan: one line, the end-card vote, or the voice, pace or language it is read in.","description":"One change per call to a ready plan made from your own script: a line in your words (lineIndex from 0, and was: the line as you last read it), the vote (null for none), or the voice, pace or language the same lines are read in. Only the length and the quote move; nothing is drawn or charged. Paid plans only.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.plans.update_script","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_plans action=update_script","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lineIndex":{"description":"The line to change, from 0 (with text).","type":"integer","minimum":0,"maximum":199},"text":{"description":"The line's new words (with lineIndex).","type":"string","maxLength":4000},"was":{"description":"The line as you last read it: a line changed since is refused.","type":"string","maxLength":4000},"vote":{"description":"The end card's vote, or null for none.","anyOf":[{"type":"object","properties":{"question":{"description":"The end card's question, 3 to 40 characters.","type":"string","minLength":3,"maxLength":40},"a":{"description":"The first choice, one short word.","type":"string","minLength":1,"maxLength":14},"b":{"description":"The second choice, one short word.","type":"string","minLength":1,"maxLength":14}},"required":["question","a","b"],"additionalProperties":false},{"type":"null"}]},"voiceId":{"description":"Narrator (Story): Who reads a Story. The last 14 (meta.v2Only) need the 20-voice switch; stickman.capabilities.get lists what is offered now. meta.sampleUrl plays a sample.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=storyVoice) to see them all.\nDefault: nPczCjzI2devNBz1zQrb. Or the voiceId of one of your own cloned voices (autoclips_voices, source \"cloned\").","type":"string","pattern":"^[A-Za-z0-9]{8,64}$"},"pace":{"description":"Reading pace: How fast the narrator reads. A faster pace fits more words into the same length.\nChoices:\n- relaxed — Relaxed: Everyday speaking pace — easiest to follow.\n- natural — Natural: Steady documentary read.\n- brisk — Brisk: Fast and punchy, still every word clear.\n- rapid — Rapid: Breathless, relentless — the hardest read to follow.\nDefault: brisk.","type":"string","enum":["relaxed","natural","brisk","rapid"]},"language":{"title":"Language (Story) (Stickman videos (Explainer, Skit, Story) option storyLanguage)","description":"Language (Story): The language of a Story's narration, cards and captions. Some languages are switched on later than others: a language that is not offered yet is refused with language_not_offered, and stickman.capabilities.get lists what is offered now.\nChoices: one of 94 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=storyLanguage) to see them all.\nDefault: en.","type":"string"},"languageConfirmed":{"type":"boolean"}},"additionalProperties":false},"example":{"pace":"natural"}}}},"parameters":[{"name":"planId","in":"path","required":true,"schema":{"description":"The plan (planId from stickman_plans create or list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The plan (planId from stickman_plans create or list).","example":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"plan":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"description":"queued, researching, awaiting_user, casting, plan-ready, started, failed or cancelled.","anyOf":[{"type":"string"},{"type":"null"}]},"lengthSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"story":{"type":"string"},"events":{"type":"array","items":{"type":"object","properties":{"at":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["at","kind","text"],"additionalProperties":false}},"question":{"description":"The Director's question while it waits for your answer (stickman_plans answer).","anyOf":[{"type":"object","properties":{"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"options":{"type":"array","items":{}}},"required":["question","options"],"additionalProperties":false},{"type":"null"}]},"pictures":{"type":"array","items":{"type":"object","properties":{"uploadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"castId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["uploadId","caption","url","kind","castId"],"additionalProperties":false}},"plan":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"hookLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"pov":{"anyOf":[{"type":"string"},{"type":"null"}]},"beats":{"type":"array","items":{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"what":{"anyOf":[{"type":"string"},{"type":"null"}]},"castIds":{"type":"array","items":{"type":"string"}},"card":{"anyOf":[{},{"type":"null"}]},"visual":{"type":"string"},"locationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"timeOfDay":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}}},"required":["n","what","castIds","card","locationId","timeOfDay"],"additionalProperties":false}},"ending":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"a":{"anyOf":[{"type":"string"},{"type":"null"}]},"b":{"anyOf":[{"type":"string"},{"type":"null"}]},"aLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"bLine":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","question","a","b","aLine","bLine"],"additionalProperties":false},{"type":"null"}]},"cards":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},{"type":"null"}]}},"required":["title","logline","hookLine","pov","beats","ending","cards"],"additionalProperties":false},{"type":"null"}]},"facts":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"claim":{"anyOf":[{"type":"string"},{"type":"null"}]},"value":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"date":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceTitle":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","claim","value","unit","date","sourceUrl","sourceTitle"],"additionalProperties":false}},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"isViewer":{"type":"boolean"},"realPerson":{"type":"boolean"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"variants":{"type":"array","items":{"type":"string"}},"pickedVariant":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"looks":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["used","max"],"additionalProperties":false}},"required":["castId","name","role","isViewer","realPerson","status","variants","pickedVariant","looks"],"additionalProperties":false}},"assets":{"type":"array","items":{"type":"object","properties":{"assetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"placement":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["assetId","kind","name","url","placement","status"],"additionalProperties":false}},"places":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","status","masterUrl","posterUrl"],"additionalProperties":false}},"props":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"states":{"type":"array","items":{"type":"string"}},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"posterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","states","status","masterUrl","posterUrl"],"additionalProperties":false}},"issues":{"type":"array","items":{}},"error":{"anyOf":[{"type":"object","properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"projectId":{"description":"The video made from this plan, once it is started.","anyOf":[{"type":"string"},{"type":"null"}]},"billing":{"description":"Credits charged so far, and what the plan has cost so far.","type":"object","properties":{"chargedCredits":{"type":"number"},"runningCredits":{"type":"number"}},"required":["chargedCredits","runningCredits"],"additionalProperties":false},"revisions":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"active":{"type":"boolean"},"error":{"anyOf":[{"type":"object","properties":{"n":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["n","code","message"],"additionalProperties":false},{"type":"null"}]}},"required":["used","max","active","error"],"additionalProperties":false},"script":{"type":"object","properties":{"lines":{"type":"array","items":{}},"label":{"anyOf":[{"type":"number"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pace":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"vote":{"anyOf":[{"type":"object","properties":{"question":{"type":"string"},"a":{"type":"string"},"b":{"type":"string"}},"required":["a","b"],"additionalProperties":false},{"type":"null"}]},"quote":{}},"required":["lines","label","voiceId","pace","language","vote","quote"],"additionalProperties":false}},"required":["id","status","lengthSeconds","story","events","question","pictures","plan","facts","cast","assets","places","props","issues","error","projectId","billing","revisions"],"additionalProperties":false}},"required":["plan"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"plan":{"id":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d","status":"plan-ready","lengthSeconds":90,"story":"You find a bag of money in a stranger's car","events":[{"at":"2026-10-25T10:00:00.000Z","kind":"status","text":"Plan ready"}],"question":null,"pictures":[],"plan":{"title":"The Bag","logline":"You find a bag of money in a stranger's car, and the stranger is watching.","hookLine":"You were only looking for your phone.","pov":"second","beats":[{"n":1,"what":"You open the wrong car door","castIds":["you"],"card":{"kind":"none","text":""},"locationId":"lot","timeOfDay":"night"}],"ending":{"type":"vote","question":"Keep it?","a":"KEEP","b":"RUN","aLine":"You keep the money.","bLine":"You run."},"cards":{"enabled":true,"theme":"night"}},"facts":[],"cast":[{"castId":"you","name":"You","role":"protagonist","isViewer":true,"realPerson":false,"status":"done","variants":["https://media.autoclips.app/stickman/you.png"],"pickedVariant":0,"looks":{"used":0,"max":5}}],"assets":[],"places":[],"props":[],"issues":[],"error":null,"projectId":null,"billing":{"chargedCredits":640,"runningCredits":640},"revisions":{"used":0,"max":5,"active":false,"error":null}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/plans/{planId}/video":{"post":{"operationId":"stickman_plans_make_video","summary":"Turn a ready plan into the video. What you approve is the video's spending limit.","description":"Makes the video from a ready plan: its scenes, cast, vote or ending. Pick the length, narrator, captions, cards, how much moves (motion: stills, key or full, paid plans), the music, your watermark and your outro (outroId, paid plans); a plan made from your script keeps its own voice and length. What you approve is the video's spending limit: the most the run can be charged (its base, its moving scenes at their cap, a cover). Each step is charged as it is made, usually much less. It answers with a job at once (status 202); follow it with autoclips_jobs get. A plan is made into one video.\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. The limit is the most Stickman video can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.plans.make_video","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_plans action=make_video","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lengthSeconds":{"description":"Story length: How long a Story (or a Story part) runs. It sets the base price; moving scenes are added on top.\nChoices:\n- 30 — 30 seconds: A 30-second story. (600 credits base (x your plan multiplier))\n- 40 — 40 seconds: A 40-second story. (750 credits base (x your plan multiplier))\n- 50 — 50 seconds: A 50-second story. (950 credits base (x your plan multiplier))\n- 60 — 1 minute: A 60-second story. (1100 credits base (x your plan multiplier))\n- 70 — 1.2 minutes: A 70-second story. (1250 credits base (x your plan multiplier))\n- 80 — 1.3 minutes: A 80-second story. (1400 credits base (x your plan multiplier))\n- 90 — 1.5 minutes: A 90-second story. (1550 credits base (x your plan multiplier))\n- 100 — 1.7 minutes: A 100-second story. (1700 credits base (x your plan multiplier))\n- 110 — 1.8 minutes: A 110-second story. (1850 credits base (x your plan multiplier))\n- 120 — 2 minutes: A 120-second story. (2000 credits base (x your plan multiplier))\nDefault: 90.","type":"string","enum":["30","40","50","60","70","80","90","100","110","120"]},"voiceId":{"description":"Narrator (Story): Who reads a Story. The last 14 (meta.v2Only) need the 20-voice switch; stickman.capabilities.get lists what is offered now. meta.sampleUrl plays a sample.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=storyVoice) to see them all.\nDefault: nPczCjzI2devNBz1zQrb. Or the voiceId of one of your own cloned voices (autoclips_voices, source \"cloned\").","type":"string","pattern":"^[A-Za-z0-9]{8,64}$"},"captions":{"description":"Show captions (default on).","type":"boolean"},"captionStyle":{"description":"The caption look. Leave a key out to keep the format's own.","type":"object","properties":{"highlightStyle":{"description":"Caption look: How the spoken words appear on screen (captionStyle.highlightStyle). The same looks every AutoClips format uses.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionStyle) to see them all.\nDefault: The format's own look (leave it out).","type":"string","enum":["classic","color-only","scale-up","typewriter","progressive","karaoke","bounce","outline","background","shadow-pop","pop-color","neon","underline","gradient","boxed","glow"]},"fontFamily":{"description":"Caption font: The lettering of the captions (captionStyle.fontFamily).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionFont) to see them all.\nDefault: The caption look's own font (leave it out).","type":"string","enum":["Montserrat","BebasNeue","Anton","LeagueSpartan"]},"position":{"description":"Caption position: Where the captions sit (captionStyle.position).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionPosition) to see them all.\nDefault: The format's own position (leave it out).","type":"string","enum":["top","upper-third","center","lower-third","bottom"]},"positionY":{"description":"Where the captions sit, 0 (top) to 100 (bottom); wins over position.","type":"number","minimum":0,"maximum":100},"groupSize":{"description":"Words at a time: How many words the captions show at once (captionStyle.groupSize, sent as a number).\nChoices:\n- 2 — 2 words: Punchy. Reads fastest.\n- 3 — 3 words: The default.\n- 4 — 4 words: Calmer, fewer changes.\nDefault: The caption look's own size (leave it out).","type":"string","enum":["2","3","4"]},"fontSize":{"description":"Caption size, 28 to 110.","type":"integer","minimum":28,"maximum":110},"color":{"description":"Caption colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"highlightColor":{"description":"The spoken word's colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"showBackground":{"description":"A box behind the captions.","type":"boolean"},"backgroundOpacity":{"description":"How solid that box is, 0 to 1.","type":"number","minimum":0,"maximum":1}},"additionalProperties":false},"cards":{"description":"The Story's text cards. Leave it out for the default.","type":"object","properties":{"enabled":{"description":"Draw the on-screen text cards (needs the cards switch: stickman.capabilities.get).","type":"boolean"},"theme":{"description":"Text card look: The look of a Story's on-screen text cards and its end card.\nChoices:\n- night — Night: Dark card, green edge.\n- ink — Ink: Dark tiles, pink accents, paper fact cards.\n- clean — Clean: White card, black text.\nDefault: Night for You Decide, Ink for True Story (leave it out).","type":"string","enum":["night","ink","clean"]}},"additionalProperties":false},"motion":{"description":"Story motion: How much of a Story moves. Moving scenes are paid plans only and are charged as each one is made, never above the quote's \"at most\". Story options (You Decide, True Story) need Stickman Story switched on for the account; stickman.capabilities.get says what is on right now.\nChoices:\n- stills — Stills: Pictures with camera moves; nothing is animated.\n- key — Key moments: The key moments of the story move. (118 credits a moving scene (a 5-second clip on AutoClips 1; storyMotionModel changes it), at most the quote's cap; plans: paid)\n- full — Full motion: Every picture scene moves. (118 credits a moving scene (a 5-second clip on AutoClips 1; storyMotionModel changes it), at most the quote's cap; plans: paid)\nDefault: stills.","type":"string","enum":["stills","key","full"]},"bestClip":{"description":"Best Clip: up to 3 takes of each moving scene, the best one kept. Every take is charged. Only with key or full motion.","type":"boolean"},"motionModel":{"description":"Story clip model: Story motion only: the AutoClips model the moving scenes are filmed with. Characters who speak (Character Speaks) are filmed on AutoClips 1 when a Lite model is picked. A next part keeps its part before's model unless you name one. Story options (You Decide, True Story) need Stickman Story switched on for the account; stickman.capabilities.get says what is on right now.\nChoices:\n- autoclips1 — AutoClips 1: Our main model, 768p. Each clip runs as long as its scene. (118 credits a moving scene (a 5-second clip); plans: paid)\n- autoclips1Upscaled — AutoClips 1 1080p Upscaled: AutoClips 1, sharpened to 1080p. (157 credits a moving scene (a 5-second clip); plans: paid)\n- autoclips1Light — AutoClips 1 Lite: Half the price, 720p. (63 credits a moving scene (a 5-second clip); talking clips are priced as AutoClips 1; plans: paid)\n- autoclips1LightHd — AutoClips 1 Lite Full HD: AutoClips 1 Lite drawn at full 1080p. (173 credits a moving scene (a 5-second clip); talking clips are priced as AutoClips 1; plans: paid)\nDefault: autoclips1.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd"]},"videoSpeed":{"description":"Video speed: How fast the finished video plays, from 1x to 3x in steps of 0.1. The page's quick picks: 1x, 1.1x, 1.2x, 1.3x, 1.5x, 2x, 3x. Free: it changes no price. From 1 to 3 x, in steps of 0.1. Default: 1.","type":"number","minimum":1,"maximum":3,"multipleOf":0.1},"musicTrackId":{"title":"Music (Stickman videos (Explainer, Skit, Story) option musicTrack)","description":"Music: A music track by id: \"none\" (no music, when an Explainer or Skit is made; a render refuses it, since a render always keeps the video's music: turn a Story's music off with the edit music.none), a track of the music library, or a Story music bed (meta.kind \"bed\"). Links are never taken: the id picks the track.\nChoices: one of 232 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=musicTrack) to see them all.\nDefault: The format's default (Story: the series bed) (leave it out).","type":"string"},"artStyle":{"description":"Art style: The look of the pictures in a Story: the places, the light and the colours. The stick figures stay the same in every style. A next part keeps the style of the part before it. meta.exampleUrl shows the same scene in each style.\nChoices:\n- default — Cinematic: Painted night scenes in teal and warm orange. The classic look. Best for any story.\n- horror — Horror Glow: Dark and creepy, lit by vivid green, red and purple light. Best for scary, survival and mystery stories.\n- noir — Rainy Noir: Rain-soaked streets, hard shadows and cold blue light. Crime and secrets. Best for crime, heists and true stories.\n- sunny — Bright Day: Sunny, colourful and cheerful, like a Saturday-morning cartoon. Best for funny, feel-good and kids stories.\n- epic — Golden Epic: Huge skies, golden sunsets and dust in the air. Feels like a movie. Best for history, war and adventure.\nDefault: default.","type":"string","enum":["default","horror","noir","sunny","epic"]},"watermarkType":{"description":"Watermark: Your text or picture on the video. Every plan.\nChoices:\n- none — None: No watermark.\n- text — Text: watermarkText.\n- image — Picture: watermarkMediaId.\nDefault: none.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"Text: The words. Default: No text (leave it out).","type":"string","minLength":1,"maxLength":50},"watermarkTextColor":{"description":"Text colour: #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundColor":{"description":"Box colour: #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundOpacity":{"description":"Box: Box, 0 (none) to 1. From 0 to 1, in steps of 0.01. Default: 0.5.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"watermarkMediaId":{"description":"A picture from autoclips_media, by id. Default: No picture (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"watermarkImageOpacity":{"description":"Picture opacity: 0.3 to 1. From 0.3 to 1, in steps of 0.01. Default: 0.7.","type":"number","minimum":0.3,"maximum":1,"multipleOf":0.01},"watermarkVerticalPosition":{"description":"Height: Percent from the top. From 10 to 90 percent. Default: 85.","type":"integer","minimum":10,"maximum":90},"watermarkHorizontalPosition":{"description":"Across: Percent from the left. From 5 to 95 percent. Default: 85.","type":"integer","minimum":5,"maximum":95},"watermarkScale":{"description":"Size: 1 is normal. From 0.5 to 3, in steps of 0.01. Default: 1.","type":"number","minimum":0.5,"maximum":3,"multipleOf":0.01},"watermarkStartSeconds":{"description":"From: Seconds into the video it appears. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"watermarkEndSeconds":{"description":"Until: Seconds into the video it goes; 0 = to the end. At least 0.5 s after the start. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"outroId":{"description":"Outro: An end card from autoclips_outros, after the last scene. Paid plans (free: plan_required). \"none\" = no outro. A Story's own end card still closes the story; the outro plays after it. Default: No outro (leave it out).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"additionalProperties":false},"example":{"lengthSeconds":"90","motion":"key"}}}},"parameters":[{"name":"planId","in":"path","required":true,"schema":{"description":"The plan (planId from stickman_plans create or list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The plan (planId from stickman_plans create or list).","example":"9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"description":"The video id (projectId).","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"type":"string","enum":["explainer","skit","story"]},"storyFlavor":{"description":"you-decide or true-story for a Story.","anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"description":"Where it is, in one word.","type":"string","enum":["queued","writing","voicing","drawing","filming","transcribing","preview_ready","rendering","completed","failed"]},"status":{"description":"The raw status word.","type":"string"},"progress":{"description":"Percent done, 0 to 100.","type":"number"},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","status"],"additionalProperties":false},"thumbnail":{"anyOf":[{"type":"object","properties":{"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","url"],"additionalProperties":false},{"type":"null"}]},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"parentProjectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextPartNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextPartProjectId":{"type":"string"}},"required":["seriesId","partNumber","parentProjectId"],"additionalProperties":false},{"type":"null"}]},"automation":{"anyOf":[{"type":"object","properties":{"automationId":{"type":"string"}},"required":["automationId"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"description":"Open it in the app.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","kind","storyFlavor","title","topic","stage","status","progress","video","thumbnail","series","automation","createdAt","updatedAt","appUrl"],"additionalProperties":false},"job":{"description":"Follow it with autoclips_jobs get. It succeeds with result.videoUrl when the video is ready.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"approvedCredits":{"description":"The spending limit you approved. Nothing is charged yet: each step is charged as it is made, usually much less.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","job","approvedCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"3f2c9a10-5b7e-4c1d-9e0f-1a2b3c4d5e6f","kind":"story","storyFlavor":"you-decide","title":"The Bag","topic":"You find a bag of money in a stranger's car","stage":"queued","status":"queued","progress":3,"video":{"url":null,"status":null},"thumbnail":null,"series":{"seriesId":"3f2c9a10-5b7e-4c1d-9e0f-1a2b3c4d5e6f","partNumber":1,"parentProjectId":null},"automation":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","appUrl":"https://app.autoclips.app/stickman?sessionId=3f2c9a10-5b7e-4c1d-9e0f-1a2b3c4d5e6f"},"job":{"id":"job_66f2a0000000000000000a01","product":"stickman","kind":"stickman.video","resource":{"type":"project","id":"3f2c9a10-5b7e-4c1d-9e0f-1a2b3c4d5e6f"},"status":"running","step":"Waiting to start","progress":3,"result":null,"error":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","finishedAt":null,"poll_after_seconds":15},"approvedCredits":4338}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects":{"post":{"operationId":"stickman_projects_create","summary":"Start a new Explainer or Skit. Paid: what you approve is its spending limit, charged step by step as it is made.","description":"Starts a new Stickman Explainer or Skit from a topic and settings, exactly as the website's Create button does, and answers at once with a job (status 202) to follow with autoclips_jobs get; it succeeds with the video link. What you approve is its spending limit, the most the run can be charged; the video is charged step by step as it is made (its base when its pictures are done, each clip when it is made) and usually costs less. The website's own credit check applies: your free credits (your balance less what videos still being made hold and finished videos owe) must cover what such a video usually needs. Leaving motion out gives Classic (no clips); the website starts on Full Motion. Your watermark (watermarkType text, or image with watermarkMediaId: one of your pictures; its colours, place, size and the seconds it shows) and your outro (outroId from autoclips_outros, paid plans) are added when the video renders, at no cost. A retry with the same Idempotency-Key answers with the same video and never starts a second one.\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. The limit is the most Stickman video can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.projects.create","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_projects action=create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"topic":{"description":"What the video is about, 3 to 300 characters (for example \"Unethical but legal ways to make money\"). The script is written from it; for your own script, word for word, use stickman_plans create with script.","type":"string","minLength":3,"maxLength":300},"mode":{"description":"Kind of video: An Explainer or a Skit. Stories start with stickman.story.quick_start or a plan instead.\nChoices:\n- explainer — Explainer: A deadpan narrator walks through an absurd scheme or dark listicle, 30 to 90 seconds.\n- skit — Skit: A ten-second animated gag built on silence, timing and one perfect punchline.\nDefault: explainer.","type":"string","enum":["explainer","skit"]},"angle":{"description":"Angle: The kind of joke the script is built on. Each angle belongs to a mode (meta.modes) and comes with example topics (meta.exampleChips, by mode); Custom takes your own topic in either mode.\nChoices:\n- unethical-money — Unethical Money: An absurd money scheme narrated like a business plan, part N of an endless series.\n- dark-hacks — Dark Hacks: A life-hack listicle where every tip is absurd and the delivery never blinks.\n- psychology — Dark Psychology: The manipulation tricks used on you every day, decoded one by one.\n- tech — Tech & AI: What the machine in your pocket is really doing, briefed like a leak.\n- survival — Dark Survival: Field-manual survival rules that drift from plausible to unhinged.\n- history — Dark History: The hidden, sinister story behind an everyday thing, read like a classified file.\n- custom — Custom: Your own topic, poured into the deadpan explainer grammar. In a Skit: your own premise, run through the skit timing machine.\n- relatable-fear — Relatable Fear: An everyday nighttime fear staged for a jump-laugh.\n- good-bad-news — Good News, Bad News: A two-character dialogue joke where the bad news is the punchline.\n- gaming — Gaming: One last game, and the passage of time that follows.\n- dev-life — Dev Life: The ten-second tragedy of shipping software, staged at one desk.\n- melancholy — Melancholy: A wordless, cinematic sad moment that lands in the chest.\nDefault: Unethical Money for an Explainer, Relatable Fear for a Skit (leave it out).","type":"string","enum":["unethical-money","dark-hacks","psychology","tech","survival","history","custom","relatable-fear","good-bad-news","gaming","dev-life","melancholy"]},"lengthSeconds":{"description":"Explainer length: How long an Explainer runs. It sets the base price; clips are added on top.\nChoices:\n- 30 — 30 seconds: A 30-second video. (600 credits base (x your plan multiplier))\n- 40 — 40 seconds: A 40-second video. (750 credits base (x your plan multiplier))\n- 50 — 50 seconds: A 50-second video. (950 credits base (x your plan multiplier))\n- 60 — 1 minute: A 60-second video. (1100 credits base (x your plan multiplier))\n- 70 — 1.2 minutes: A 70-second video. (1250 credits base (x your plan multiplier))\n- 80 — 1.3 minutes: A 80-second video. (1400 credits base (x your plan multiplier))\n- 90 — 1.5 minutes: A 90-second video. (1550 credits base (x your plan multiplier))\nDefault: 60.","type":"string","enum":["30","40","50","60","70","80","90"]},"motion":{"description":"Explainer motion: How much of an Explainer moves. Leaving it out gives Classic; the website starts a new video on Full Motion. Moving clips are priced by the clip model.\nChoices:\n- classic — Classic: Cinematic zooms sweep across every scene.\n- enhanced — Enhanced: Key scenes come alive with real motion. (Adds 2 clips, each priced by the clip model)\n- full — Full Motion: Every single scene is animated with real motion. (Adds one clip a scene (7 to 18 scenes by length), each priced by the clip model)\nDefault: classic.","type":"string","enum":["classic","enhanced","full"]},"clipModel":{"description":"Clip model: Which model makes an Explainer's moving clips (Enhanced and Full Motion). A clip AutoClips 1 cannot make is made by a backup model, billed at the backup's price.\nChoices:\n- autoclips1 — AutoClips 1: Our main model, 768p. Each clip runs as long as its scene. (Billed by the second, 15 credits a second (5 to 15 seconds a clip): from 80 a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- autoclips1Upscaled — AutoClips 1 1080p Upscaled: AutoClips 1, sharpened to 1080p. (Billed by the second, 20 credits a second (5 to 15 seconds a clip): from 107 a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- autoclips1Light — AutoClips 1 Lite: Half the price, 720p. (Billed by the second, 8 credits a second (5 to 15 seconds a clip): from 43 a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- autoclips1LightHd — AutoClips 1 Lite Full HD: AutoClips 1 Lite drawn at full 1080p. (Billed by the second, 23 credits a second (5 to 15 seconds a clip): from 118 a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- omniMax — Pro Max: Flat price per clip. (805 credits a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- kling3 — Pro: Handles darker scenes. (805 credits a clip (x your plan multiplier), its planning included)\n- autoclips — AutoClips 1 (old name): The old name of autoclips1, still taken. Send autoclips1 instead. (As AutoClips 1)\nDefault: autoclips1.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd","omniMax","kling3","autoclips"]},"clipSource":{"description":"Full Motion clips from: What Full Motion clips are made from: each scene's picture, or the script alone.\nChoices:\n- image — From pictures: Every scene is drawn first, then animated. The best look.\n- text — From text: Animated straight from the script, no pictures drawn. A little less polished. (A lower base, 350 to 900 credits by length; Full Motion on an AutoClips clip model only (the one picked, else AutoClips 1))\nDefault: image.","type":"string","enum":["image","text"]},"voiceId":{"description":"Narrator (Explainer): Who reads an Explainer. meta.sampleUrl plays the same line in each voice.\nChoices:\n- nPczCjzI2devNBz1zQrb — Brian: Deep, relentless deadpan — the signature stickman read.\n- JBFqnCBsd6RMkjVDRZzb — George: British documentary storyteller, brisk and crisp.\n- EXAVITQu4vr4xnSDxMaL — Sarah: Confident, matter-of-fact professional.\n- pNInz6obpgDQGcFmaJgB — Adam: Deep and dominant — cuts through the feed instantly.\n- TxGEqnHWrfWFTfGW9XjX — Josh: Clear, engaging classic narrator.\n- onwK4e9ZLuTAKqWW03F9 — Daniel: Calm broadcast narrator, most measured read.\nDefault: nPczCjzI2devNBz1zQrb.","type":"string","enum":["nPczCjzI2devNBz1zQrb","JBFqnCBsd6RMkjVDRZzb","EXAVITQu4vr4xnSDxMaL","pNInz6obpgDQGcFmaJgB","TxGEqnHWrfWFTfGW9XjX","onwK4e9ZLuTAKqWW03F9"]},"pace":{"description":"Reading pace: How fast the narrator reads. A faster pace fits more words into the same length.\nChoices:\n- relaxed — Relaxed: Everyday speaking pace — easiest to follow.\n- natural — Natural: Steady documentary read.\n- brisk — Brisk: Fast and punchy, still every word clear.\n- rapid — Rapid: Breathless, relentless — the hardest read to follow.\nDefault: brisk.","type":"string","enum":["relaxed","natural","brisk","rapid"]},"skitModel":{"description":"Skit quality: Which quality tier makes a Skit's clips. A Skit has one to four clips; the joke decides how many.\nChoices:\n- omniMax — Pro Max: 8-second clips, the best quality and the fastest to make. (800 credits a clip (x your plan multiplier); a clip it cannot make is made by Pro at 1000)\n- kling3 — Pro: 10-second clips with the most cinematic motion. (1000 credits a clip (x your plan multiplier))\n- veo31lite — Lite: Quick and affordable 8-second clips. (500 credits a clip (x your plan multiplier))\nDefault: omniMax.","type":"string","enum":["omniMax","kling3","veo31lite"]},"language":{"description":"The spoken language code (stickman.capabilities.get lists what each kind of video speaks right now).","type":"string","minLength":2,"maxLength":16},"videoSpeed":{"description":"Video speed: How fast the finished video plays, from 1x to 3x in steps of 0.1. The page's quick picks: 1x, 1.1x, 1.2x, 1.3x, 1.5x, 2x, 3x. Free: it changes no price. From 1 to 3 x, in steps of 0.1. Default: 1.","type":"number","minimum":1,"maximum":3,"multipleOf":0.1},"captions":{"description":"Captions on the video (default on).","type":"boolean"},"captionStyle":{"description":"The caption look. Leave a key out to keep the format's own.","type":"object","properties":{"highlightStyle":{"description":"Caption look: How the spoken words appear on screen (captionStyle.highlightStyle). The same looks every AutoClips format uses.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionStyle) to see them all.\nDefault: The format's own look (leave it out).","type":"string","enum":["classic","color-only","scale-up","typewriter","progressive","karaoke","bounce","outline","background","shadow-pop","pop-color","neon","underline","gradient","boxed","glow"]},"fontFamily":{"description":"Caption font: The lettering of the captions (captionStyle.fontFamily).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionFont) to see them all.\nDefault: The caption look's own font (leave it out).","type":"string","enum":["Montserrat","BebasNeue","Anton","LeagueSpartan"]},"position":{"description":"Caption position: Where the captions sit (captionStyle.position).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionPosition) to see them all.\nDefault: The format's own position (leave it out).","type":"string","enum":["top","upper-third","center","lower-third","bottom"]},"positionY":{"description":"Where the captions sit, 0 (top) to 100 (bottom); wins over position.","type":"number","minimum":0,"maximum":100},"groupSize":{"description":"Words at a time: How many words the captions show at once (captionStyle.groupSize, sent as a number).\nChoices:\n- 2 — 2 words: Punchy. Reads fastest.\n- 3 — 3 words: The default.\n- 4 — 4 words: Calmer, fewer changes.\nDefault: The caption look's own size (leave it out).","type":"string","enum":["2","3","4"]},"fontSize":{"description":"Caption size, 28 to 110.","type":"integer","minimum":28,"maximum":110},"color":{"description":"Caption colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"highlightColor":{"description":"The spoken word's colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"showBackground":{"description":"A box behind the captions.","type":"boolean"},"backgroundOpacity":{"description":"How solid that box is, 0 to 1.","type":"number","minimum":0,"maximum":1}},"additionalProperties":false},"musicTrackId":{"title":"Music (Stickman videos (Explainer, Skit, Story) option musicTrack)","description":"Music: A music track by id: \"none\" (no music, when an Explainer or Skit is made; a render refuses it, since a render always keeps the video's music: turn a Story's music off with the edit music.none), a track of the music library, or a Story music bed (meta.kind \"bed\"). Links are never taken: the id picks the track.\nChoices: one of 232 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=musicTrack) to see them all.\nDefault: The format's default (Story: the series bed) (leave it out).","type":"string"},"watermarkType":{"description":"Watermark: Your text or picture on the video. Every plan.\nChoices:\n- none — None: No watermark.\n- text — Text: watermarkText.\n- image — Picture: watermarkMediaId.\nDefault: none.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"Text: The words. Default: No text (leave it out).","type":"string","minLength":1,"maxLength":50},"watermarkTextColor":{"description":"Text colour: #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundColor":{"description":"Box colour: #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundOpacity":{"description":"Box: Box, 0 (none) to 1. From 0 to 1, in steps of 0.01. Default: 0.5.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"watermarkMediaId":{"description":"A picture from autoclips_media, by id. Default: No picture (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"watermarkImageOpacity":{"description":"Picture opacity: 0.3 to 1. From 0.3 to 1, in steps of 0.01. Default: 0.7.","type":"number","minimum":0.3,"maximum":1,"multipleOf":0.01},"watermarkVerticalPosition":{"description":"Height: Percent from the top. From 10 to 90 percent. Default: 85.","type":"integer","minimum":10,"maximum":90},"watermarkHorizontalPosition":{"description":"Across: Percent from the left. From 5 to 95 percent. Default: 85.","type":"integer","minimum":5,"maximum":95},"watermarkScale":{"description":"Size: 1 is normal. From 0.5 to 3, in steps of 0.01. Default: 1.","type":"number","minimum":0.5,"maximum":3,"multipleOf":0.01},"watermarkStartSeconds":{"description":"From: Seconds into the video it appears. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"watermarkEndSeconds":{"description":"Until: Seconds into the video it goes; 0 = to the end. At least 0.5 s after the start. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"outroId":{"description":"Outro: An end card from autoclips_outros, after the last scene. Paid plans (free: plan_required). \"none\" = no outro. A Story's own end card still closes the story; the outro plays after it. Default: No outro (leave it out).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["topic"],"additionalProperties":false},"example":{"topic":"A deadpan business plan for bottling plain air from famous cities","lengthSeconds":"60"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"description":"The video's projectId.","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"explainer, skit or story.","type":"string","enum":["explainer","skit","story"]},"storyFlavor":{"description":"A Story's kind (You Decide or True Story); null for others.","anyOf":[{"type":"string","enum":["you-decide","true-story"]},{"type":"null"}]},"title":{"type":"string"},"topic":{"description":"What it was asked to be about.","anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"description":"Where it is: queued, writing, voicing, drawing, filming, transcribing, preview_ready, rendering, completed or failed.","type":"string","enum":["queued","writing","voicing","drawing","filming","transcribing","preview_ready","rendering","completed","failed"]},"status":{"description":"The raw status word.","type":"string"},"progress":{"type":"integer","minimum":0,"maximum":100},"video":{"description":"The finished video, once rendered.","type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","status"],"additionalProperties":false},"thumbnail":{"anyOf":[{"type":"object","properties":{"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","url"],"additionalProperties":false},{"type":"null"}]},"series":{"description":"A Story part's series, or null.","anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"parentProjectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextPartNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextPartProjectId":{"type":"string"}},"required":["seriesId","partNumber","parentProjectId"],"additionalProperties":false},{"type":"null"}]},"automation":{"description":"The automation that made it, or null.","anyOf":[{"type":"object","properties":{"automationId":{"type":"string"}},"required":["automationId"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"description":"Open it in the app.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","kind","storyFlavor","title","topic","stage","status","progress","video","thumbnail","series","automation","createdAt","updatedAt","appUrl"],"additionalProperties":false},"job":{"description":"Follow it with autoclips_jobs get. It succeeds with result.videoUrl.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"approvedCredits":{"description":"The spending limit you approved. Nothing is charged yet; each step is charged as it is made.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"settings":{"description":"Every setting the video is made with, defaults filled in.","type":"object","properties":{"mode":{"type":"string","enum":["explainer","skit"]},"angle":{"type":"string"},"lengthSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"motion":{"anyOf":[{"type":"string"},{"type":"null"}]},"clipModel":{"anyOf":[{"type":"string"},{"type":"null"}]},"clipSource":{"anyOf":[{"type":"string"},{"type":"null"}]},"skitModel":{"anyOf":[{"type":"string"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pace":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"type":"string"},"videoSpeed":{"type":"number"},"captions":{"type":"boolean"},"captionStyle":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"music":{"description":"null: no music.","anyOf":[{"type":"object","properties":{"trackId":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["trackId","title"],"additionalProperties":false},{"type":"null"}]}},"required":["mode","angle","lengthSeconds","motion","clipModel","clipSource","skitModel","voiceId","pace","language","videoSpeed","captions","captionStyle","music"],"additionalProperties":false}},"required":["project","job","approvedCredits","settings"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f","kind":"explainer","storyFlavor":null,"title":"Sell Air From Famous Cities","topic":"A deadpan business plan for bottling plain air from famous cities","stage":"queued","status":"queued","progress":3,"video":{"url":null,"status":"idle"},"thumbnail":null,"series":null,"automation":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","appUrl":"https://app.autoclips.app/stickman?sessionId=6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"},"job":{"id":"job_0199a2b3c4d5e6f708192a3b","product":"stickman","kind":"stickman.video","resource":{"type":"project","id":"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"},"status":"running","step":"Waiting to start","progress":3,"result":null,"error":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","finishedAt":null,"poll_after_seconds":10},"approvedCredits":1120,"settings":{"mode":"explainer","angle":"unethical-money","lengthSeconds":60,"motion":"classic","clipModel":null,"clipSource":null,"skitModel":null,"voiceId":"nPczCjzI2devNBz1zQrb","pace":"brisk","language":"en","videoSpeed":1,"captions":true,"captionStyle":null,"music":null}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"stickman_projects_list","summary":"Your recent Stickman videos, newest first, with their stage and link.","description":"Your most recently changed Stickman videos (Explainers, Skits and Story parts), newest first, as the website's Recent projects shows them: videos that got somewhere (a video that stopped before its first picture is left out). A Story part says its series and whether its next part exists.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.projects.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_projects action=list","parameters":[{"name":"limit","in":"query","required":false,"schema":{"description":"How many (1-50, default 20).","default":20,"type":"integer","minimum":1,"maximum":50},"description":"How many (1-50, default 20).","example":5}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The video's projectId.","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"explainer, skit or story.","type":"string","enum":["explainer","skit","story"]},"storyFlavor":{"description":"A Story's kind (You Decide or True Story); null for others.","anyOf":[{"type":"string","enum":["you-decide","true-story"]},{"type":"null"}]},"title":{"type":"string"},"topic":{"description":"What it was asked to be about.","anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"description":"Where it is: queued, writing, voicing, drawing, filming, transcribing, preview_ready, rendering, completed or failed.","type":"string","enum":["queued","writing","voicing","drawing","filming","transcribing","preview_ready","rendering","completed","failed"]},"status":{"description":"The raw status word.","type":"string"},"progress":{"type":"integer","minimum":0,"maximum":100},"video":{"description":"The finished video, once rendered.","type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","status"],"additionalProperties":false},"thumbnail":{"anyOf":[{"type":"object","properties":{"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","url"],"additionalProperties":false},{"type":"null"}]},"series":{"description":"A Story part's series, or null.","anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"parentProjectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextPartNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextPartProjectId":{"type":"string"}},"required":["seriesId","partNumber","parentProjectId"],"additionalProperties":false},{"type":"null"}]},"automation":{"description":"The automation that made it, or null.","anyOf":[{"type":"object","properties":{"automationId":{"type":"string"}},"required":["automationId"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"description":"Open it in the app.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","kind","storyFlavor","title","topic","stage","status","progress","video","thumbnail","series","automation","createdAt","updatedAt","appUrl"],"additionalProperties":false}}},"required":["projects"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"projects":[{"id":"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f","kind":"explainer","storyFlavor":null,"title":"Sell Air From Famous Cities","topic":"A deadpan business plan for bottling plain air from famous cities","stage":"completed","status":"completed","progress":100,"video":{"url":"https://media.autoclips.app/stickman/videos/example.mp4","status":"completed"},"thumbnail":{"status":"ready","url":"https://media.autoclips.app/stickman/scenes/example-1.png"},"series":null,"automation":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","appUrl":"https://app.autoclips.app/stickman?sessionId=6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/quote":{"post":{"operationId":"stickman_projects_quote","summary":"The spending limit an Explainer or Skit with these settings would ask for, what it usually costs, and your free credits.","description":"Prices a new Explainer or Skit without starting anything: the spending limit create would ask you to approve (the most it can be charged, line by line), what it usually costs, your free credits (your balance less what videos still being made hold), and every setting it would be made with. Settings that do not fit together are refused here as create would refuse them.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.projects.quote","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_projects action=quote","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"topic":{"description":"What the video is about, 3 to 300 characters (for example \"Unethical but legal ways to make money\"). The script is written from it; for your own script, word for word, use stickman_plans create with script.","type":"string","minLength":3,"maxLength":300},"mode":{"description":"Kind of video: An Explainer or a Skit. Stories start with stickman.story.quick_start or a plan instead.\nChoices:\n- explainer — Explainer: A deadpan narrator walks through an absurd scheme or dark listicle, 30 to 90 seconds.\n- skit — Skit: A ten-second animated gag built on silence, timing and one perfect punchline.\nDefault: explainer.","type":"string","enum":["explainer","skit"]},"angle":{"description":"Angle: The kind of joke the script is built on. Each angle belongs to a mode (meta.modes) and comes with example topics (meta.exampleChips, by mode); Custom takes your own topic in either mode.\nChoices:\n- unethical-money — Unethical Money: An absurd money scheme narrated like a business plan, part N of an endless series.\n- dark-hacks — Dark Hacks: A life-hack listicle where every tip is absurd and the delivery never blinks.\n- psychology — Dark Psychology: The manipulation tricks used on you every day, decoded one by one.\n- tech — Tech & AI: What the machine in your pocket is really doing, briefed like a leak.\n- survival — Dark Survival: Field-manual survival rules that drift from plausible to unhinged.\n- history — Dark History: The hidden, sinister story behind an everyday thing, read like a classified file.\n- custom — Custom: Your own topic, poured into the deadpan explainer grammar. In a Skit: your own premise, run through the skit timing machine.\n- relatable-fear — Relatable Fear: An everyday nighttime fear staged for a jump-laugh.\n- good-bad-news — Good News, Bad News: A two-character dialogue joke where the bad news is the punchline.\n- gaming — Gaming: One last game, and the passage of time that follows.\n- dev-life — Dev Life: The ten-second tragedy of shipping software, staged at one desk.\n- melancholy — Melancholy: A wordless, cinematic sad moment that lands in the chest.\nDefault: Unethical Money for an Explainer, Relatable Fear for a Skit (leave it out).","type":"string","enum":["unethical-money","dark-hacks","psychology","tech","survival","history","custom","relatable-fear","good-bad-news","gaming","dev-life","melancholy"]},"lengthSeconds":{"description":"Explainer length: How long an Explainer runs. It sets the base price; clips are added on top.\nChoices:\n- 30 — 30 seconds: A 30-second video. (600 credits base (x your plan multiplier))\n- 40 — 40 seconds: A 40-second video. (750 credits base (x your plan multiplier))\n- 50 — 50 seconds: A 50-second video. (950 credits base (x your plan multiplier))\n- 60 — 1 minute: A 60-second video. (1100 credits base (x your plan multiplier))\n- 70 — 1.2 minutes: A 70-second video. (1250 credits base (x your plan multiplier))\n- 80 — 1.3 minutes: A 80-second video. (1400 credits base (x your plan multiplier))\n- 90 — 1.5 minutes: A 90-second video. (1550 credits base (x your plan multiplier))\nDefault: 60.","type":"string","enum":["30","40","50","60","70","80","90"]},"motion":{"description":"Explainer motion: How much of an Explainer moves. Leaving it out gives Classic; the website starts a new video on Full Motion. Moving clips are priced by the clip model.\nChoices:\n- classic — Classic: Cinematic zooms sweep across every scene.\n- enhanced — Enhanced: Key scenes come alive with real motion. (Adds 2 clips, each priced by the clip model)\n- full — Full Motion: Every single scene is animated with real motion. (Adds one clip a scene (7 to 18 scenes by length), each priced by the clip model)\nDefault: classic.","type":"string","enum":["classic","enhanced","full"]},"clipModel":{"description":"Clip model: Which model makes an Explainer's moving clips (Enhanced and Full Motion). A clip AutoClips 1 cannot make is made by a backup model, billed at the backup's price.\nChoices:\n- autoclips1 — AutoClips 1: Our main model, 768p. Each clip runs as long as its scene. (Billed by the second, 15 credits a second (5 to 15 seconds a clip): from 80 a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- autoclips1Upscaled — AutoClips 1 1080p Upscaled: AutoClips 1, sharpened to 1080p. (Billed by the second, 20 credits a second (5 to 15 seconds a clip): from 107 a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- autoclips1Light — AutoClips 1 Lite: Half the price, 720p. (Billed by the second, 8 credits a second (5 to 15 seconds a clip): from 43 a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- autoclips1LightHd — AutoClips 1 Lite Full HD: AutoClips 1 Lite drawn at full 1080p. (Billed by the second, 23 credits a second (5 to 15 seconds a clip): from 118 a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- omniMax — Pro Max: Flat price per clip. (805 credits a clip (x your plan multiplier), its planning included; a backup clip costs at most 805)\n- kling3 — Pro: Handles darker scenes. (805 credits a clip (x your plan multiplier), its planning included)\n- autoclips — AutoClips 1 (old name): The old name of autoclips1, still taken. Send autoclips1 instead. (As AutoClips 1)\nDefault: autoclips1.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd","omniMax","kling3","autoclips"]},"clipSource":{"description":"Full Motion clips from: What Full Motion clips are made from: each scene's picture, or the script alone.\nChoices:\n- image — From pictures: Every scene is drawn first, then animated. The best look.\n- text — From text: Animated straight from the script, no pictures drawn. A little less polished. (A lower base, 350 to 900 credits by length; Full Motion on an AutoClips clip model only (the one picked, else AutoClips 1))\nDefault: image.","type":"string","enum":["image","text"]},"voiceId":{"description":"Narrator (Explainer): Who reads an Explainer. meta.sampleUrl plays the same line in each voice.\nChoices:\n- nPczCjzI2devNBz1zQrb — Brian: Deep, relentless deadpan — the signature stickman read.\n- JBFqnCBsd6RMkjVDRZzb — George: British documentary storyteller, brisk and crisp.\n- EXAVITQu4vr4xnSDxMaL — Sarah: Confident, matter-of-fact professional.\n- pNInz6obpgDQGcFmaJgB — Adam: Deep and dominant — cuts through the feed instantly.\n- TxGEqnHWrfWFTfGW9XjX — Josh: Clear, engaging classic narrator.\n- onwK4e9ZLuTAKqWW03F9 — Daniel: Calm broadcast narrator, most measured read.\nDefault: nPczCjzI2devNBz1zQrb.","type":"string","enum":["nPczCjzI2devNBz1zQrb","JBFqnCBsd6RMkjVDRZzb","EXAVITQu4vr4xnSDxMaL","pNInz6obpgDQGcFmaJgB","TxGEqnHWrfWFTfGW9XjX","onwK4e9ZLuTAKqWW03F9"]},"pace":{"description":"Reading pace: How fast the narrator reads. A faster pace fits more words into the same length.\nChoices:\n- relaxed — Relaxed: Everyday speaking pace — easiest to follow.\n- natural — Natural: Steady documentary read.\n- brisk — Brisk: Fast and punchy, still every word clear.\n- rapid — Rapid: Breathless, relentless — the hardest read to follow.\nDefault: brisk.","type":"string","enum":["relaxed","natural","brisk","rapid"]},"skitModel":{"description":"Skit quality: Which quality tier makes a Skit's clips. A Skit has one to four clips; the joke decides how many.\nChoices:\n- omniMax — Pro Max: 8-second clips, the best quality and the fastest to make. (800 credits a clip (x your plan multiplier); a clip it cannot make is made by Pro at 1000)\n- kling3 — Pro: 10-second clips with the most cinematic motion. (1000 credits a clip (x your plan multiplier))\n- veo31lite — Lite: Quick and affordable 8-second clips. (500 credits a clip (x your plan multiplier))\nDefault: omniMax.","type":"string","enum":["omniMax","kling3","veo31lite"]},"language":{"description":"The spoken language code (stickman.capabilities.get lists what each kind of video speaks right now).","type":"string","minLength":2,"maxLength":16},"videoSpeed":{"description":"Video speed: How fast the finished video plays, from 1x to 3x in steps of 0.1. The page's quick picks: 1x, 1.1x, 1.2x, 1.3x, 1.5x, 2x, 3x. Free: it changes no price. From 1 to 3 x, in steps of 0.1. Default: 1.","type":"number","minimum":1,"maximum":3,"multipleOf":0.1},"captions":{"description":"Captions on the video (default on).","type":"boolean"},"captionStyle":{"description":"The caption look. Leave a key out to keep the format's own.","type":"object","properties":{"highlightStyle":{"description":"Caption look: How the spoken words appear on screen (captionStyle.highlightStyle). The same looks every AutoClips format uses.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionStyle) to see them all.\nDefault: The format's own look (leave it out).","type":"string","enum":["classic","color-only","scale-up","typewriter","progressive","karaoke","bounce","outline","background","shadow-pop","pop-color","neon","underline","gradient","boxed","glow"]},"fontFamily":{"description":"Caption font: The lettering of the captions (captionStyle.fontFamily).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionFont) to see them all.\nDefault: The caption look's own font (leave it out).","type":"string","enum":["Montserrat","BebasNeue","Anton","LeagueSpartan"]},"position":{"description":"Caption position: Where the captions sit (captionStyle.position).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionPosition) to see them all.\nDefault: The format's own position (leave it out).","type":"string","enum":["top","upper-third","center","lower-third","bottom"]},"positionY":{"description":"Where the captions sit, 0 (top) to 100 (bottom); wins over position.","type":"number","minimum":0,"maximum":100},"groupSize":{"description":"Words at a time: How many words the captions show at once (captionStyle.groupSize, sent as a number).\nChoices:\n- 2 — 2 words: Punchy. Reads fastest.\n- 3 — 3 words: The default.\n- 4 — 4 words: Calmer, fewer changes.\nDefault: The caption look's own size (leave it out).","type":"string","enum":["2","3","4"]},"fontSize":{"description":"Caption size, 28 to 110.","type":"integer","minimum":28,"maximum":110},"color":{"description":"Caption colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"highlightColor":{"description":"The spoken word's colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"showBackground":{"description":"A box behind the captions.","type":"boolean"},"backgroundOpacity":{"description":"How solid that box is, 0 to 1.","type":"number","minimum":0,"maximum":1}},"additionalProperties":false},"musicTrackId":{"title":"Music (Stickman videos (Explainer, Skit, Story) option musicTrack)","description":"Music: A music track by id: \"none\" (no music, when an Explainer or Skit is made; a render refuses it, since a render always keeps the video's music: turn a Story's music off with the edit music.none), a track of the music library, or a Story music bed (meta.kind \"bed\"). Links are never taken: the id picks the track.\nChoices: one of 232 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=musicTrack) to see them all.\nDefault: The format's default (Story: the series bed) (leave it out).","type":"string"}},"additionalProperties":false},"example":{"topic":"Sell air from famous cities","lengthSeconds":"60"}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"credits":{"description":"The spending limit create asks you to approve.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"breakdown":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["label","credits"],"additionalProperties":false}},"usualCredits":{"description":"About what a video like this usually costs.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"neededFreeCredits":{"description":"The free credits a start needs (the website's own check).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"freeCredits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"canStart":{"type":"boolean"},"blocker":{"description":"Why it cannot start right now, or null.","anyOf":[{"type":"string"},{"type":"null"}]},"notes":{"type":"array","items":{"type":"string"}},"important":{"type":"array","items":{"type":"string"}},"settings":{"description":"Every setting the video is made with, defaults filled in.","type":"object","properties":{"mode":{"type":"string","enum":["explainer","skit"]},"angle":{"type":"string"},"lengthSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"motion":{"anyOf":[{"type":"string"},{"type":"null"}]},"clipModel":{"anyOf":[{"type":"string"},{"type":"null"}]},"clipSource":{"anyOf":[{"type":"string"},{"type":"null"}]},"skitModel":{"anyOf":[{"type":"string"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pace":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"type":"string"},"videoSpeed":{"type":"number"},"captions":{"type":"boolean"},"captionStyle":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"music":{"description":"null: no music.","anyOf":[{"type":"object","properties":{"trackId":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["trackId","title"],"additionalProperties":false},{"type":"null"}]}},"required":["mode","angle","lengthSeconds","motion","clipModel","clipSource","skitModel","voiceId","pace","language","videoSpeed","captions","captionStyle","music"],"additionalProperties":false}},"required":["credits","breakdown","usualCredits","neededFreeCredits","freeCredits","canStart","blocker","notes","important","settings"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"credits":1120,"breakdown":[{"label":"Video base (60 s)","credits":1100},{"label":"Cover picture when the video is ready (only if your account makes covers)","credits":20}],"usualCredits":1100,"neededFreeCredits":1100,"freeCredits":5000,"canStart":true,"blocker":null,"notes":["Charged step by step as the video is made: the base when its pictures are done. Usually about 1,100."],"important":["The website starts a new Explainer on Full Motion; this one uses Classic (camera moves, no clips). Send motion to pick another."],"settings":{"mode":"explainer","angle":"unethical-money","lengthSeconds":60,"motion":"classic","clipModel":null,"clipSource":null,"skitModel":null,"voiceId":"nPczCjzI2devNBz1zQrb","pace":"brisk","language":"en","videoSpeed":1,"captions":true,"captionStyle":null,"music":null}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/{projectId}":{"get":{"operationId":"stickman_projects_get","summary":"One video: its stage, current step, any error in plain words, credits used, and the sections you ask for.","description":"One Stickman video: its stage and progress, what it is doing, why it stopped (in plain words), the credits it charged so far, a Story's vote and series, and the video link once it is rendered. Ask for more with include: settings, scenes, narration, post, editing, motion, steps.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.projects.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_projects action=get","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The video (projectId from stickman_projects list or create).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The video (projectId from stickman_projects list or create).","example":"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"},{"name":"include","in":"query","required":false,"schema":{"description":"Extra sections: settings, scenes, narration, post, editing, motion, steps.","maxItems":7,"type":"array","items":{"type":"string","enum":["settings","scenes","narration","post","editing","motion","steps"]}},"description":"Extra sections: settings, scenes, narration, post, editing, motion, steps.","example":["settings"]}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"The video's projectId.","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"explainer, skit or story.","type":"string","enum":["explainer","skit","story"]},"storyFlavor":{"description":"A Story's kind (You Decide or True Story); null for others.","anyOf":[{"type":"string","enum":["you-decide","true-story"]},{"type":"null"}]},"title":{"type":"string"},"topic":{"description":"What it was asked to be about.","anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"description":"Where it is: queued, writing, voicing, drawing, filming, transcribing, preview_ready, rendering, completed or failed.","type":"string","enum":["queued","writing","voicing","drawing","filming","transcribing","preview_ready","rendering","completed","failed"]},"status":{"description":"The raw status word.","type":"string"},"progress":{"type":"integer","minimum":0,"maximum":100},"video":{"description":"The finished video, once rendered.","type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","status"],"additionalProperties":false},"thumbnail":{"anyOf":[{"type":"object","properties":{"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","url"],"additionalProperties":false},{"type":"null"}]},"series":{"description":"A Story part's series, or null.","anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"parentProjectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextPartNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextPartProjectId":{"type":"string"}},"required":["seriesId","partNumber","parentProjectId"],"additionalProperties":false},{"type":"null"}]},"automation":{"description":"The automation that made it, or null.","anyOf":[{"type":"object","properties":{"automationId":{"type":"string"}},"required":["automationId"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"description":"Open it in the app.","anyOf":[{"type":"string"},{"type":"null"}]},"currentStep":{"description":"What it is doing, in plain words.","type":"string"},"error":{"description":"Why it stopped, in plain words, or null.","anyOf":[{"type":"object","properties":{"step":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"type":"string"}},"required":["step","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"description":"Credits charged so far, and the website's estimate.","type":"object","properties":{"used":{"type":"number"},"estimated":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["used","estimated"],"additionalProperties":false},"story":{"description":"A Story's vote and series words.","type":"object","properties":{"vote":{"anyOf":[{"type":"object","properties":{"question":{"type":"string"},"a":{"type":"string"},"b":{"type":"string"}},"required":["a","b"],"additionalProperties":false},{"type":"null"}]},"voteResult":{"anyOf":[{"type":"object","properties":{"winner":{"type":"string"},"loser":{"anyOf":[{"type":"string"},{"type":"null"}]},"percent":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["winner","loser","percent"],"additionalProperties":false},{"type":"null"}]},"ending":{"anyOf":[{"type":"string","enum":["vote","follow"]},{"type":"null"}]},"seriesTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"chapter":{"type":"boolean"},"finalPart":{"type":"boolean"},"plannedParts":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"artStyle":{"description":"The art style its pictures were drawn in (autoclips_options: artStyle).","type":"string"}},"required":["vote","voteResult","ending","seriesTitle","chapter","finalPart","plannedParts"],"additionalProperties":false},"settings":{"description":"The settings the video is made with.","type":"object","properties":{"mode":{"type":"string","enum":["explainer","skit"]},"angle":{"anyOf":[{"type":"string"},{"type":"null"}]},"lengthSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"motion":{"anyOf":[{"type":"string"},{"type":"null"}]},"clipModel":{"anyOf":[{"type":"string"},{"type":"null"}]},"clipSource":{"anyOf":[{"type":"string"},{"type":"null"}]},"skitModel":{"anyOf":[{"type":"string"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pace":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"type":"string"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoSpeed":{"type":"number"},"captions":{"type":"boolean"},"captionStyle":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"music":{"anyOf":[{"anyOf":[{"type":"object","properties":{"trackId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["trackId","title"],"additionalProperties":false},{"type":"object","properties":{"off":{"type":"boolean","const":true}},"required":["off"],"additionalProperties":false}]},{"type":"null"}]},"cards":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},{"type":"null"}]},"storyMotion":{"anyOf":[{"type":"object","properties":{"tier":{"type":"string"},"bestClip":{"type":"boolean"},"model":{"description":"The AutoClips model the moving scenes film with.","type":"string"},"aboutCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"capCredits":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["tier","bestClip","model","aboutCredits","capCredits"],"additionalProperties":false},{"type":"null"}]},"watermarkType":{"description":"none, text or image.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"A text watermark's words, or null.","anyOf":[{"type":"string"},{"type":"null"}]},"watermarkTextColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundOpacity":{"description":"0 to 1","type":"number"},"watermarkImageOpacity":{"description":"0.3 to 1","type":"number"},"watermarkVerticalPosition":{"description":"Percent from the top.","type":"number"},"watermarkHorizontalPosition":{"description":"Percent from the left.","type":"number"},"watermarkScale":{"description":"1 is normal.","type":"number"},"watermarkStartSeconds":{"description":"Seconds.","type":"number"},"watermarkEndSeconds":{"description":"Seconds; 0 = to the end.","type":"number"},"outroId":{"description":"Or null.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["mode","angle","lengthSeconds","motion","clipModel","clipSource","skitModel","voiceId","pace","language","videoSpeed","captions","captionStyle","music"],"additionalProperties":false},"scenes":{"description":"Each scene: its words, picture, clip and state.","type":"array","items":{"type":"object","properties":{"index":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["index"],"additionalProperties":{}}},"narration":{"anyOf":[{"type":"object","properties":{"audioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["audioUrl","durationMs","voiceId"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags","tags"],"additionalProperties":false},{"type":"null"}]},"editing":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"motion":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","label","status"],"additionalProperties":false}}},"required":["id","kind","storyFlavor","title","topic","stage","status","progress","video","thumbnail","series","automation","createdAt","updatedAt","appUrl","currentStep","error","credits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"id":"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f","kind":"explainer","storyFlavor":null,"title":"Sell Air From Famous Cities","topic":"A deadpan business plan for bottling plain air from famous cities","stage":"completed","status":"completed","progress":100,"video":{"url":"https://media.autoclips.app/stickman/videos/example.mp4","status":"completed"},"thumbnail":{"status":"ready","url":"https://media.autoclips.app/stickman/scenes/example-1.png"},"series":null,"automation":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","appUrl":"https://app.autoclips.app/stickman?sessionId=6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f","currentStep":"Done","error":null,"credits":{"used":1100,"estimated":1100},"settings":{"mode":"explainer","angle":"unethical-money","lengthSeconds":60,"motion":"classic","clipModel":null,"clipSource":null,"skitModel":null,"voiceId":"nPczCjzI2devNBz1zQrb","pace":"brisk","language":"en","videoSpeed":1,"captions":true,"captionStyle":null,"music":null}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"stickman_projects_update","summary":"Change captions, their look, a Story's cards, the video speed, your watermark or your outro. Render it again to see it.","description":"Changes a video that is made (ready to render, or rendered): captions on or off, their look (keys you leave out keep their current value), a Story's on-screen cards and their look, and the video speed (an Explainer or a Story; a Skit plays at 1x). Your watermark (watermarkType and the other watermark fields; only the ones you send change) and your outro (outroId, paid plans; \"none\" takes it off) can also change while the video is still being made, but not while it renders. Free. The change shows in the next render (stickman_projects render).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.projects.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_projects action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"captions":{"description":"Captions on or off.","type":"boolean"},"captionStyle":{"description":"The caption look. Leave a key out to keep the format's own.","type":"object","properties":{"highlightStyle":{"description":"Caption look: How the spoken words appear on screen (captionStyle.highlightStyle). The same looks every AutoClips format uses.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionStyle) to see them all.\nDefault: The format's own look (leave it out).","type":"string","enum":["classic","color-only","scale-up","typewriter","progressive","karaoke","bounce","outline","background","shadow-pop","pop-color","neon","underline","gradient","boxed","glow"]},"fontFamily":{"description":"Caption font: The lettering of the captions (captionStyle.fontFamily).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionFont) to see them all.\nDefault: The caption look's own font (leave it out).","type":"string","enum":["Montserrat","BebasNeue","Anton","LeagueSpartan"]},"position":{"description":"Caption position: Where the captions sit (captionStyle.position).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionPosition) to see them all.\nDefault: The format's own position (leave it out).","type":"string","enum":["top","upper-third","center","lower-third","bottom"]},"positionY":{"description":"Where the captions sit, 0 (top) to 100 (bottom); wins over position.","type":"number","minimum":0,"maximum":100},"groupSize":{"description":"Words at a time: How many words the captions show at once (captionStyle.groupSize, sent as a number).\nChoices:\n- 2 — 2 words: Punchy. Reads fastest.\n- 3 — 3 words: The default.\n- 4 — 4 words: Calmer, fewer changes.\nDefault: The caption look's own size (leave it out).","type":"string","enum":["2","3","4"]},"fontSize":{"description":"Caption size, 28 to 110.","type":"integer","minimum":28,"maximum":110},"color":{"description":"Caption colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"highlightColor":{"description":"The spoken word's colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"showBackground":{"description":"A box behind the captions.","type":"boolean"},"backgroundOpacity":{"description":"How solid that box is, 0 to 1.","type":"number","minimum":0,"maximum":1}},"additionalProperties":false},"cards":{"description":"A Story's on-screen cards: on or off, and their look.","type":"object","properties":{"enabled":{"description":"On-screen text cards on or off.","type":"boolean"},"theme":{"description":"Text card look: The look of a Story's on-screen text cards and its end card.\nChoices:\n- night — Night: Dark card, green edge.\n- ink — Ink: Dark tiles, pink accents, paper fact cards.\n- clean — Clean: White card, black text.\nDefault: Night for You Decide, Ink for True Story (leave it out).","type":"string","enum":["night","ink","clean"]}},"additionalProperties":false},"videoSpeed":{"description":"Video speed: How fast the finished video plays, from 1x to 3x in steps of 0.1. The page's quick picks: 1x, 1.1x, 1.2x, 1.3x, 1.5x, 2x, 3x. Free: it changes no price. From 1 to 3 x, in steps of 0.1. Default: 1.","type":"number","minimum":1,"maximum":3,"multipleOf":0.1},"watermarkType":{"description":"Watermark: Your text or picture on the video. Every plan.\nChoices:\n- none — None: No watermark.\n- text — Text: watermarkText.\n- image — Picture: watermarkMediaId.\nDefault: none.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"Text: The words. Default: No text (leave it out).","type":"string","minLength":1,"maxLength":50},"watermarkTextColor":{"description":"Text colour: #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundColor":{"description":"Box colour: #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundOpacity":{"description":"Box: Box, 0 (none) to 1. From 0 to 1, in steps of 0.01. Default: 0.5.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"watermarkMediaId":{"description":"A picture from autoclips_media, by id. Default: No picture (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"watermarkImageOpacity":{"description":"Picture opacity: 0.3 to 1. From 0.3 to 1, in steps of 0.01. Default: 0.7.","type":"number","minimum":0.3,"maximum":1,"multipleOf":0.01},"watermarkVerticalPosition":{"description":"Height: Percent from the top. From 10 to 90 percent. Default: 85.","type":"integer","minimum":10,"maximum":90},"watermarkHorizontalPosition":{"description":"Across: Percent from the left. From 5 to 95 percent. Default: 85.","type":"integer","minimum":5,"maximum":95},"watermarkScale":{"description":"Size: 1 is normal. From 0.5 to 3, in steps of 0.01. Default: 1.","type":"number","minimum":0.5,"maximum":3,"multipleOf":0.01},"watermarkStartSeconds":{"description":"From: Seconds into the video it appears. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"watermarkEndSeconds":{"description":"Until: Seconds into the video it goes; 0 = to the end. At least 0.5 s after the start. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"outroId":{"description":"Outro: An end card from autoclips_outros, after the last scene. Paid plans (free: plan_required). \"none\" = no outro. A Story's own end card still closes the story; the outro plays after it. Default: No outro (leave it out).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"additionalProperties":false},"example":{"captionStyle":{"fontSize":80},"videoSpeed":1.2}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The video (projectId from stickman_projects list or create).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The video (projectId from stickman_projects list or create).","example":"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"description":"The video's projectId.","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"explainer, skit or story.","type":"string","enum":["explainer","skit","story"]},"storyFlavor":{"description":"A Story's kind (You Decide or True Story); null for others.","anyOf":[{"type":"string","enum":["you-decide","true-story"]},{"type":"null"}]},"title":{"type":"string"},"topic":{"description":"What it was asked to be about.","anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"description":"Where it is: queued, writing, voicing, drawing, filming, transcribing, preview_ready, rendering, completed or failed.","type":"string","enum":["queued","writing","voicing","drawing","filming","transcribing","preview_ready","rendering","completed","failed"]},"status":{"description":"The raw status word.","type":"string"},"progress":{"type":"integer","minimum":0,"maximum":100},"video":{"description":"The finished video, once rendered.","type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","status"],"additionalProperties":false},"thumbnail":{"anyOf":[{"type":"object","properties":{"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","url"],"additionalProperties":false},{"type":"null"}]},"series":{"description":"A Story part's series, or null.","anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"parentProjectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextPartNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextPartProjectId":{"type":"string"}},"required":["seriesId","partNumber","parentProjectId"],"additionalProperties":false},{"type":"null"}]},"automation":{"description":"The automation that made it, or null.","anyOf":[{"type":"object","properties":{"automationId":{"type":"string"}},"required":["automationId"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"description":"Open it in the app.","anyOf":[{"type":"string"},{"type":"null"}]},"currentStep":{"description":"What it is doing, in plain words.","type":"string"},"error":{"description":"Why it stopped, in plain words, or null.","anyOf":[{"type":"object","properties":{"step":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"type":"string"}},"required":["step","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"description":"Credits charged so far, and the website's estimate.","type":"object","properties":{"used":{"type":"number"},"estimated":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["used","estimated"],"additionalProperties":false},"story":{"description":"A Story's vote and series words.","type":"object","properties":{"vote":{"anyOf":[{"type":"object","properties":{"question":{"type":"string"},"a":{"type":"string"},"b":{"type":"string"}},"required":["a","b"],"additionalProperties":false},{"type":"null"}]},"voteResult":{"anyOf":[{"type":"object","properties":{"winner":{"type":"string"},"loser":{"anyOf":[{"type":"string"},{"type":"null"}]},"percent":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["winner","loser","percent"],"additionalProperties":false},{"type":"null"}]},"ending":{"anyOf":[{"type":"string","enum":["vote","follow"]},{"type":"null"}]},"seriesTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"chapter":{"type":"boolean"},"finalPart":{"type":"boolean"},"plannedParts":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"artStyle":{"description":"The art style its pictures were drawn in (autoclips_options: artStyle).","type":"string"}},"required":["vote","voteResult","ending","seriesTitle","chapter","finalPart","plannedParts"],"additionalProperties":false},"settings":{"description":"The settings the video is made with.","type":"object","properties":{"mode":{"type":"string","enum":["explainer","skit"]},"angle":{"anyOf":[{"type":"string"},{"type":"null"}]},"lengthSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"motion":{"anyOf":[{"type":"string"},{"type":"null"}]},"clipModel":{"anyOf":[{"type":"string"},{"type":"null"}]},"clipSource":{"anyOf":[{"type":"string"},{"type":"null"}]},"skitModel":{"anyOf":[{"type":"string"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pace":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"type":"string"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoSpeed":{"type":"number"},"captions":{"type":"boolean"},"captionStyle":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"music":{"anyOf":[{"anyOf":[{"type":"object","properties":{"trackId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["trackId","title"],"additionalProperties":false},{"type":"object","properties":{"off":{"type":"boolean","const":true}},"required":["off"],"additionalProperties":false}]},{"type":"null"}]},"cards":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"theme":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","theme"],"additionalProperties":false},{"type":"null"}]},"storyMotion":{"anyOf":[{"type":"object","properties":{"tier":{"type":"string"},"bestClip":{"type":"boolean"},"model":{"description":"The AutoClips model the moving scenes film with.","type":"string"},"aboutCredits":{"anyOf":[{"type":"number"},{"type":"null"}]},"capCredits":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["tier","bestClip","model","aboutCredits","capCredits"],"additionalProperties":false},{"type":"null"}]},"watermarkType":{"description":"none, text or image.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"A text watermark's words, or null.","anyOf":[{"type":"string"},{"type":"null"}]},"watermarkTextColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundColor":{"description":"#RRGGBB","type":"string"},"watermarkBackgroundOpacity":{"description":"0 to 1","type":"number"},"watermarkImageOpacity":{"description":"0.3 to 1","type":"number"},"watermarkVerticalPosition":{"description":"Percent from the top.","type":"number"},"watermarkHorizontalPosition":{"description":"Percent from the left.","type":"number"},"watermarkScale":{"description":"1 is normal.","type":"number"},"watermarkStartSeconds":{"description":"Seconds.","type":"number"},"watermarkEndSeconds":{"description":"Seconds; 0 = to the end.","type":"number"},"outroId":{"description":"Or null.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["mode","angle","lengthSeconds","motion","clipModel","clipSource","skitModel","voiceId","pace","language","videoSpeed","captions","captionStyle","music"],"additionalProperties":false},"scenes":{"description":"Each scene: its words, picture, clip and state.","type":"array","items":{"type":"object","properties":{"index":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["index"],"additionalProperties":{}}},"narration":{"anyOf":[{"type":"object","properties":{"audioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["audioUrl","durationMs","voiceId"],"additionalProperties":false},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hashtags":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}},"required":["title","description","hashtags","tags"],"additionalProperties":false},{"type":"null"}]},"editing":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"motion":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","label","status"],"additionalProperties":false}}},"required":["id","kind","storyFlavor","title","topic","stage","status","progress","video","thumbnail","series","automation","createdAt","updatedAt","appUrl","currentStep","error","credits"],"additionalProperties":false}},"required":["project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f","kind":"explainer","storyFlavor":null,"title":"Sell Air From Famous Cities","topic":"A deadpan business plan for bottling plain air from famous cities","stage":"completed","status":"completed","progress":100,"video":{"url":"https://media.autoclips.app/stickman/videos/example.mp4","status":"completed"},"thumbnail":{"status":"ready","url":"https://media.autoclips.app/stickman/scenes/example-1.png"},"series":null,"automation":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","appUrl":"https://app.autoclips.app/stickman?sessionId=6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f","currentStep":"Done","error":null,"credits":{"used":1100,"estimated":1100},"settings":{"mode":"explainer","angle":"unethical-money","lengthSeconds":60,"motion":"classic","clipModel":null,"clipSource":null,"skitModel":null,"voiceId":"nPczCjzI2devNBz1zQrb","pace":"brisk","language":"en","videoSpeed":1.2,"captions":true,"captionStyle":{"fontSize":80},"music":null}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"stickman_projects_delete","summary":"Delete a video. It cannot be undone, and nothing it charged is refunded.","description":"Deletes a Stickman video and everything it made. It cannot be undone, and nothing it charged is refunded. A video still being made, rendering or changing cannot be deleted until it is done; nor can the part an automation's series goes on from (pause the automation first).\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"stickman.projects.delete","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_projects action=delete","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The video (projectId from stickman_projects list or create).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The video (projectId from stickman_projects list or create).","example":"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"projectId":{"type":"string"}},"required":["deleted","projectId"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"deleted":true,"projectId":"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/{projectId}/edits":{"post":{"operationId":"stickman_edits_apply","summary":"Apply up to 20 changes that make nothing new: text cards, graphics, captions, music, speed, earlier pictures and clips, staging.","description":"Applies up to 20 editor changes to a finished Story video in one write, guarded by baseRevision (the editing.revision you read). These changes make nothing new and are not charged: text cards (add, edit, move, remove, their look), a scene turned into a full-screen graphic and back, captions (on, look, one word's spelling), the music (a track by id, one of the video's own music takes, off, volume), the video's speed, an earlier picture or clip of a scene, another scene's picture, a picture you added, a moving scene back to a still, and who stands where. Each edit names its type and the fields that type takes (editType in autoclips_options). Scenes are named by their index (scenes[].index), cards by { sceneIndex, at, kind, anchor } as read. The changes show in the video after stickman_projects render. A 409 stale_revision means the video changed since you read it: read it again and send the changes again.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.edits.apply","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_edit action=apply","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"baseRevision":{"description":"The editing.revision you read (stickman_projects get, include editing); an older one is refused (409 stale_revision).","type":"integer","minimum":0,"maximum":9007199254740991},"edits":{"description":"1 to 20 changes, applied in order (apply_paid takes the ones that make new things).","minItems":1,"maxItems":20,"type":"array","items":{"anyOf":[{"description":"Change a card's fields.","type":"object","properties":{"type":{"type":"string","const":"card.edit"},"ref":{"description":"Which card: its scene, its position and what it was when you read it.","type":"object","properties":{"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"at":{"description":"The card's position in the scene's cards (from 0).","type":"integer","minimum":0,"maximum":9},"kind":{"description":"The card's kind, as read.","type":"string","enum":["counter","tag","label","stamp","message","list","line","fact","name","clock","hud","unitGrid","compareBars"]},"anchor":{"description":"The card's anchor, as read.","type":"string","maxLength":120}},"required":["sceneIndex","at","kind"],"additionalProperties":false},"fields":{"description":"The card fields to change; the rest stay.","type":"object","properties":{"anchor":{"description":"The 1-6 words of this scene's line the card pops on, copied exactly.","type":"string","minLength":1,"maxLength":120},"slot":{"description":"Where a text card sits.","type":"string","enum":["top","tag","center","lower"]},"text":{"description":"The card's text (tag and stamp 18, label 28).","type":"string","minLength":1,"maxLength":28},"accent":{"description":"Part of the text in the accent colour.","type":"string","minLength":1,"maxLength":20},"kicker":{"description":"Small heading above the number or fact.","type":"string","minLength":1,"maxLength":32},"to":{"description":"Counter: counts to this.","type":"number"},"from":{"description":"Counter: starts from this (0).","type":"number"},"prefix":{"description":"Counter: currency sign before it.","type":"string","enum":["$","€","£"]},"suffix":{"description":"Counter: unit after it.","type":"string","enum":["%","KG","LB","K","M","B"]},"decimals":{"description":"Counter: decimal places.","type":"integer","minimum":0,"maximum":2},"sub":{"description":"A small line under the main one.","type":"string","minLength":1,"maxLength":32},"currency":{"description":"Counter: ISO currency of a non-English amount.","type":"string","pattern":"^[A-Za-z]{3}$"},"compact":{"description":"Counter: big numbers in short form.","type":"boolean"},"sender":{"description":"Message: who sent it.","type":"string","minLength":1,"maxLength":24},"lines":{"description":"Message: up to 3 lines.","minItems":1,"maxItems":3,"type":"array","items":{"description":"One line.","type":"string","minLength":1,"maxLength":70}},"accentLine":{"description":"Message: the accent line (from 0).","type":"integer","minimum":0,"maximum":2},"title":{"description":"List: its title.","type":"string","minLength":1,"maxLength":24},"items":{"description":"List: 1-4 items. Bars: 2-4 bars, each { label, value, display }.","minItems":1,"maxItems":4,"type":"array","items":{"anyOf":[{"description":"An item.","type":"string","minLength":1,"maxLength":32},{"type":"object","properties":{"text":{"description":"The item.","type":"string","minLength":1,"maxLength":32},"anchor":{"description":"The words of the line it pops on.","type":"string","maxLength":120}},"required":["text"],"additionalProperties":false},{"type":"object","properties":{"label":{"description":"The bar's label.","type":"string","minLength":1,"maxLength":14},"value":{"description":"The bar's value (0 or more).","type":"number","minimum":0},"display":{"description":"The value as shown, e.g. \"$4.2M\".","type":"string","minLength":1,"maxLength":14},"highlight":{"description":"Draw this bar in the accent colour.","type":"boolean"}},"required":["label","value","display"],"additionalProperties":false}]}},"small":{"description":"Line card: the small line.","type":"string","minLength":1,"maxLength":28},"big":{"description":"Line card: the big line.","type":"string","minLength":1,"maxLength":24},"headline":{"description":"Fact: the headline.","type":"string","minLength":1,"maxLength":60},"factId":{"description":"Fact: a fact id of this video (its source line).","type":"string","minLength":1,"maxLength":40},"castId":{"description":"A cast id of this story (\"you\" is the viewer).","type":"string","minLength":1,"maxLength":40},"role":{"description":"Name card: who they are.","type":"string","minLength":1,"maxLength":24},"label":{"description":"Clock: its label.","type":"string","minLength":1,"maxLength":20},"value":{"description":"Clock: its value.","type":"string","minLength":1,"maxLength":12},"values":{"description":"HUD: 1-3 meter values by chip id.","type":"object","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,15}$"},"additionalProperties":{"anyOf":[{"type":"number"},{"description":"A short value.","type":"string","minLength":1,"maxLength":12}]}},"delta":{"description":"HUD: the change shown next to it.","type":"string","minLength":1,"maxLength":16},"icon":{"description":"Icon grid: the icon.","type":"string","enum":["bill","bar","coin","box","person","dot"]},"perIcon":{"description":"Icon grid: what one icon stands for.","type":"string","minLength":1,"maxLength":28},"count":{"description":"Icon grid: how many icons.","type":"integer","minimum":1,"maximum":400},"total":{"description":"Icon grid: the total as shown.","type":"string","minLength":1,"maxLength":20},"unit":{"description":"Bars: the unit.","type":"string","minLength":1,"maxLength":10}},"additionalProperties":false}},"required":["type","ref","fields"],"additionalProperties":false},{"description":"Move a text card to another word, slot or scene.","type":"object","properties":{"type":{"type":"string","const":"card.move"},"ref":{"description":"Which card: its scene, its position and what it was when you read it.","type":"object","properties":{"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"at":{"description":"The card's position in the scene's cards (from 0).","type":"integer","minimum":0,"maximum":9},"kind":{"description":"The card's kind, as read.","type":"string","enum":["counter","tag","label","stamp","message","list","line","fact","name","clock","hud","unitGrid","compareBars"]},"anchor":{"description":"The card's anchor, as read.","type":"string","maxLength":120}},"required":["sceneIndex","at","kind"],"additionalProperties":false},"toSceneIndex":{"description":"Move it to this scene (its anchor must be in that scene's line, or send anchor).","type":"integer","minimum":0,"maximum":199},"anchor":{"description":"The words it pops on now.","type":"string","minLength":1,"maxLength":120},"slot":{"description":"Where it sits now.","type":"string","enum":["top","tag","center","lower"]}},"required":["type","ref"],"additionalProperties":false},{"description":"Remove a text card.","type":"object","properties":{"type":{"type":"string","const":"card.remove"},"ref":{"description":"Which card: its scene, its position and what it was when you read it.","type":"object","properties":{"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"at":{"description":"The card's position in the scene's cards (from 0).","type":"integer","minimum":0,"maximum":9},"kind":{"description":"The card's kind, as read.","type":"string","enum":["counter","tag","label","stamp","message","list","line","fact","name","clock","hud","unitGrid","compareBars"]},"anchor":{"description":"The card's anchor, as read.","type":"string","maxLength":120}},"required":["sceneIndex","at","kind"],"additionalProperties":false}},"required":["type","ref"],"additionalProperties":false},{"description":"Add a text card to a scene (at most 2 a scene).","type":"object","properties":{"type":{"type":"string","const":"card.add"},"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"card":{"description":"The new card: its kind, its anchor and the fields its kind needs.","type":"object","properties":{"anchor":{"description":"The 1-6 words of this scene's line the card pops on, copied exactly.","type":"string","minLength":1,"maxLength":120},"slot":{"description":"Where a text card sits.","type":"string","enum":["top","tag","center","lower"]},"text":{"description":"The card's text (tag and stamp 18, label 28).","type":"string","minLength":1,"maxLength":28},"accent":{"description":"Part of the text in the accent colour.","type":"string","minLength":1,"maxLength":20},"kicker":{"description":"Small heading above the number or fact.","type":"string","minLength":1,"maxLength":32},"to":{"description":"Counter: counts to this.","type":"number"},"from":{"description":"Counter: starts from this (0).","type":"number"},"prefix":{"description":"Counter: currency sign before it.","type":"string","enum":["$","€","£"]},"suffix":{"description":"Counter: unit after it.","type":"string","enum":["%","KG","LB","K","M","B"]},"decimals":{"description":"Counter: decimal places.","type":"integer","minimum":0,"maximum":2},"sub":{"description":"A small line under the main one.","type":"string","minLength":1,"maxLength":32},"currency":{"description":"Counter: ISO currency of a non-English amount.","type":"string","pattern":"^[A-Za-z]{3}$"},"compact":{"description":"Counter: big numbers in short form.","type":"boolean"},"sender":{"description":"Message: who sent it.","type":"string","minLength":1,"maxLength":24},"lines":{"description":"Message: up to 3 lines.","minItems":1,"maxItems":3,"type":"array","items":{"description":"One line.","type":"string","minLength":1,"maxLength":70}},"accentLine":{"description":"Message: the accent line (from 0).","type":"integer","minimum":0,"maximum":2},"title":{"description":"List: its title.","type":"string","minLength":1,"maxLength":24},"items":{"description":"List: 1-4 items. Bars: 2-4 bars, each { label, value, display }.","minItems":1,"maxItems":4,"type":"array","items":{"anyOf":[{"description":"An item.","type":"string","minLength":1,"maxLength":32},{"type":"object","properties":{"text":{"description":"The item.","type":"string","minLength":1,"maxLength":32},"anchor":{"description":"The words of the line it pops on.","type":"string","maxLength":120}},"required":["text"],"additionalProperties":false},{"type":"object","properties":{"label":{"description":"The bar's label.","type":"string","minLength":1,"maxLength":14},"value":{"description":"The bar's value (0 or more).","type":"number","minimum":0},"display":{"description":"The value as shown, e.g. \"$4.2M\".","type":"string","minLength":1,"maxLength":14},"highlight":{"description":"Draw this bar in the accent colour.","type":"boolean"}},"required":["label","value","display"],"additionalProperties":false}]}},"small":{"description":"Line card: the small line.","type":"string","minLength":1,"maxLength":28},"big":{"description":"Line card: the big line.","type":"string","minLength":1,"maxLength":24},"headline":{"description":"Fact: the headline.","type":"string","minLength":1,"maxLength":60},"factId":{"description":"Fact: a fact id of this video (its source line).","type":"string","minLength":1,"maxLength":40},"castId":{"description":"A cast id of this story (\"you\" is the viewer).","type":"string","minLength":1,"maxLength":40},"role":{"description":"Name card: who they are.","type":"string","minLength":1,"maxLength":24},"label":{"description":"Clock: its label.","type":"string","minLength":1,"maxLength":20},"value":{"description":"Clock: its value.","type":"string","minLength":1,"maxLength":12},"values":{"description":"HUD: 1-3 meter values by chip id.","type":"object","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,15}$"},"additionalProperties":{"anyOf":[{"type":"number"},{"description":"A short value.","type":"string","minLength":1,"maxLength":12}]}},"delta":{"description":"HUD: the change shown next to it.","type":"string","minLength":1,"maxLength":16},"icon":{"description":"Icon grid: the icon.","type":"string","enum":["bill","bar","coin","box","person","dot"]},"perIcon":{"description":"Icon grid: what one icon stands for.","type":"string","minLength":1,"maxLength":28},"count":{"description":"Icon grid: how many icons.","type":"integer","minimum":1,"maximum":400},"total":{"description":"Icon grid: the total as shown.","type":"string","minLength":1,"maxLength":20},"unit":{"description":"Bars: the unit.","type":"string","minLength":1,"maxLength":10},"kind":{"description":"The kind of text card (cardKind in autoclips_options).","type":"string","enum":["counter","tag","label","stamp","message","list","line","fact","name","clock","hud"]}},"required":["anchor","kind"],"additionalProperties":false}},"required":["type","sceneIndex","card"],"additionalProperties":false},{"description":"Turn the text cards on or off, or change their look.","type":"object","properties":{"type":{"type":"string","const":"cards.look"},"enabled":{"description":"Show the text cards.","type":"boolean"},"theme":{"description":"Text card look: The look of a Story's on-screen text cards and its end card.\nChoices:\n- night — Night: Dark card, green edge.\n- ink — Ink: Dark tiles, pink accents, paper fact cards.\n- clean — Clean: White card, black text.\nDefault: Night for You Decide, Ink for True Story (leave it out).","type":"string","enum":["night","ink","clean"]}},"required":["type"],"additionalProperties":false},{"description":"Turn a scene into a full-screen graphic (bars, icon grid or fact).","type":"object","properties":{"type":{"type":"string","const":"graphic.convert"},"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"card":{"description":"The graphic: anchored on the number the line says. Its fields are card.add's card fields.","type":"object","properties":{"anchor":{"description":"The 1-6 words of this scene's line the card pops on, copied exactly.","type":"string","minLength":1,"maxLength":120},"text":{"type":"string","minLength":1,"maxLength":28},"accent":{"type":"string","minLength":1,"maxLength":20},"kicker":{"type":"string","minLength":1,"maxLength":32},"to":{"type":"number"},"from":{"type":"number"},"prefix":{"type":"string","enum":["$","€","£"]},"suffix":{"type":"string","enum":["%","KG","LB","K","M","B"]},"decimals":{"type":"integer","minimum":0,"maximum":2},"sub":{"type":"string","minLength":1,"maxLength":32},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$"},"compact":{"type":"boolean"},"sender":{"type":"string","minLength":1,"maxLength":24},"lines":{"minItems":1,"maxItems":3,"type":"array","items":{"description":"One line.","type":"string","minLength":1,"maxLength":70}},"accentLine":{"type":"integer","minimum":0,"maximum":2},"title":{"type":"string","minLength":1,"maxLength":24},"items":{"minItems":1,"maxItems":4,"type":"array","items":{"anyOf":[{"description":"An item.","type":"string","minLength":1,"maxLength":32},{"type":"object","properties":{"text":{"description":"The item.","type":"string","minLength":1,"maxLength":32},"anchor":{"description":"The words of the line it pops on.","type":"string","maxLength":120}},"required":["text"],"additionalProperties":false},{"type":"object","properties":{"label":{"description":"The bar's label.","type":"string","minLength":1,"maxLength":14},"value":{"description":"The bar's value (0 or more).","type":"number","minimum":0},"display":{"description":"The value as shown, e.g. \"$4.2M\".","type":"string","minLength":1,"maxLength":14},"highlight":{"description":"Draw this bar in the accent colour.","type":"boolean"}},"required":["label","value","display"],"additionalProperties":false}]}},"small":{"type":"string","minLength":1,"maxLength":28},"big":{"type":"string","minLength":1,"maxLength":24},"headline":{"type":"string","minLength":1,"maxLength":60},"factId":{"type":"string","minLength":1,"maxLength":40},"castId":{"type":"string","minLength":1,"maxLength":40},"role":{"type":"string","minLength":1,"maxLength":24},"label":{"type":"string","minLength":1,"maxLength":20},"value":{"type":"string","minLength":1,"maxLength":12},"values":{"type":"object","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,15}$"},"additionalProperties":{"anyOf":[{"type":"number"},{"description":"A short value.","type":"string","minLength":1,"maxLength":12}]}},"delta":{"type":"string","minLength":1,"maxLength":16},"icon":{"type":"string","enum":["bill","bar","coin","box","person","dot"]},"perIcon":{"type":"string","minLength":1,"maxLength":28},"count":{"type":"integer","minimum":1,"maximum":400},"total":{"type":"string","minLength":1,"maxLength":20},"unit":{"type":"string","minLength":1,"maxLength":10},"kind":{"description":"Bars, an icon grid or a fact.","type":"string","enum":["unitGrid","compareBars","fact"]}},"required":["anchor","kind"],"additionalProperties":false}},"required":["type","sceneIndex","card"],"additionalProperties":false},{"description":"Turn a graphic scene back into its picture.","type":"object","properties":{"type":{"type":"string","const":"graphic.revert"},"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199}},"required":["type","sceneIndex"],"additionalProperties":false},{"description":"Turn captions on or off, or change their look.","type":"object","properties":{"type":{"type":"string","const":"captions.set"},"enabled":{"description":"Show captions.","type":"boolean"},"style":{"description":"The caption look. Leave a key out to keep the format's own.","type":"object","properties":{"highlightStyle":{"description":"Caption look: How the spoken words appear on screen (captionStyle.highlightStyle). The same looks every AutoClips format uses.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionStyle) to see them all.\nDefault: The format's own look (leave it out).","type":"string","enum":["classic","color-only","scale-up","typewriter","progressive","karaoke","bounce","outline","background","shadow-pop","pop-color","neon","underline","gradient","boxed","glow"]},"fontFamily":{"description":"Caption font: The lettering of the captions (captionStyle.fontFamily).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionFont) to see them all.\nDefault: The caption look's own font (leave it out).","type":"string","enum":["Montserrat","BebasNeue","Anton","LeagueSpartan"]},"position":{"description":"Caption position: Where the captions sit (captionStyle.position).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionPosition) to see them all.\nDefault: The format's own position (leave it out).","type":"string","enum":["top","upper-third","center","lower-third","bottom"]},"positionY":{"description":"Where the captions sit, 0 (top) to 100 (bottom); wins over position.","type":"number","minimum":0,"maximum":100},"groupSize":{"description":"Words at a time: How many words the captions show at once (captionStyle.groupSize, sent as a number).\nChoices:\n- 2 — 2 words: Punchy. Reads fastest.\n- 3 — 3 words: The default.\n- 4 — 4 words: Calmer, fewer changes.\nDefault: The caption look's own size (leave it out).","type":"string","enum":["2","3","4"]},"fontSize":{"description":"Caption size, 28 to 110.","type":"integer","minimum":28,"maximum":110},"color":{"description":"Caption colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"highlightColor":{"description":"The spoken word's colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"showBackground":{"description":"A box behind the captions.","type":"boolean"},"backgroundOpacity":{"description":"How solid that box is, 0 to 1.","type":"number","minimum":0,"maximum":1}},"additionalProperties":false}},"required":["type"],"additionalProperties":false},{"description":"Fix how one caption word is written.","type":"object","properties":{"type":{"type":"string","const":"captions.fix"},"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"wordIndex":{"description":"The word's position in the scene's captions (from 0).","type":"integer","minimum":0,"maximum":999},"text":{"description":"What the caption shows instead; empty gives the spoken word back.","type":"string","maxLength":40}},"required":["type","sceneIndex","wordIndex","text"],"additionalProperties":false},{"description":"Play another track: a musicTrack id, or one of the video's music takes (send exactly one).","type":"object","properties":{"type":{"type":"string","const":"music.pick"},"trackId":{"title":"Music (Stickman videos (Explainer, Skit, Story) option musicTrack)","description":"Music: A music track by id: \"none\" (no music, when an Explainer or Skit is made; a render refuses it, since a render always keeps the video's music: turn a Story's music off with the edit music.none), a track of the music library, or a Story music bed (meta.kind \"bed\"). Links are never taken: the id picks the track.\nChoices: one of 232 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=musicTrack) to see them all.\nDefault: The format's default (Story: the series bed) (leave it out).","type":"string"},"takeId":{"description":"One of this video's own music takes (made with music.make).","type":"string","minLength":1,"maxLength":80}},"required":["type"],"additionalProperties":false},{"description":"Turn the music off.","type":"object","properties":{"type":{"type":"string","const":"music.none"}},"required":["type"],"additionalProperties":false},{"description":"Make the music louder or quieter.","type":"object","properties":{"type":{"type":"string","const":"music.volume"},"db":{"description":"Music volume in dB, -12 to +6.","type":"number","minimum":-12,"maximum":6,"multipleOf":0.5}},"required":["type","db"],"additionalProperties":false},{"description":"Play the finished video faster (applied on the next render).","type":"object","properties":{"type":{"type":"string","const":"video.speed"},"speed":{"description":"Video speed: How fast the finished video plays, from 1x to 3x in steps of 0.1. The page's quick picks: 1x, 1.1x, 1.2x, 1.3x, 1.5x, 2x, 3x. Free: it changes no price. From 1 to 3 x, in steps of 0.1. Default: 1.","type":"number","minimum":1,"maximum":3,"multipleOf":0.1}},"required":["type","speed"],"additionalProperties":false},{"description":"Show an earlier picture of the scene.","type":"object","properties":{"type":{"type":"string","const":"picture.take"},"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"takeId":{"description":"A take id from the scene's takes (stickman_projects get, include scenes).","type":"string","minLength":1,"maxLength":80}},"required":["type","sceneIndex","takeId"],"additionalProperties":false},{"description":"Use another scene's picture.","type":"object","properties":{"type":{"type":"string","const":"picture.swap"},"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"fromSceneIndex":{"description":"The scene whose picture to use.","type":"integer","minimum":0,"maximum":199}},"required":["type","sceneIndex","fromSceneIndex"],"additionalProperties":false},{"description":"Use a picture you added (stickman_story upload_image), shown as it is.","type":"object","properties":{"type":{"type":"string","const":"picture.upload"},"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"uploadId":{"description":"A picture added with stickman_story upload_image.","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"required":["type","sceneIndex","uploadId"],"additionalProperties":false},{"description":"Make a moving scene a still picture again.","type":"object","properties":{"type":{"type":"string","const":"clip.remove"},"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199}},"required":["type","sceneIndex"],"additionalProperties":false},{"description":"Say who is where in a scene, or whose hand holds the thing (no new picture).","type":"object","properties":{"type":{"type":"string","const":"scene.stage"},"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"blocking":{"anyOf":[{"description":"Who is where, one entry per person in the scene.","maxItems":6,"type":"array","items":{"type":"object","properties":{"castId":{"description":"A cast id of this story (\"you\" is the viewer).","type":"string","minLength":1,"maxLength":40},"where":{"description":"Where they are, in English, e.g. \"behind the counter\".","type":"string","maxLength":80},"side":{"description":"in (in the shot), out (out of it), door, screen.","type":"string","enum":["in","out","door","screen"]}},"required":["castId","where","side"],"additionalProperties":false}},{"type":"null"}]},"heldBy":{"description":"Whose hand holds the thing: a cast id, \"you\", or null for nobody.","anyOf":[{"type":"string","minLength":1,"maxLength":40},{"type":"null"}]}},"required":["type","sceneIndex"],"additionalProperties":false},{"description":"Play another clip this scene made.","type":"object","properties":{"type":{"type":"string","const":"clip.take"},"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"takeId":{"description":"A take id from the scene's takes (stickman_projects get, include scenes).","type":"string","minLength":1,"maxLength":80}},"required":["type","sceneIndex","takeId"],"additionalProperties":false}]}}},"required":["baseRevision","edits"],"additionalProperties":false},"example":{"baseRevision":3,"edits":[{"type":"captions.set","enabled":true,"style":{"fontSize":64}},{"type":"music.volume","db":-3}]}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The video (projectId from stickman_projects list or create).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The video (projectId from stickman_projects list or create).","example":"6f1d2c9a-3b7e-4f58-a0d4-9c2e7b1a5f30"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"revision":{"description":"The video's editing revision now: send it with the next change.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"seq":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"editIds":{"description":"One id per change, in order (stickman_edit history).","type":"array","items":{"type":"string"}},"warnings":{"description":"What the editor adjusted or noticed, in plain words.","type":"array","items":{"type":"string"}},"project":{"description":"The video after the change (see stickman_projects get), with its editing state and scenes.","type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"type":"string"},"title":{"type":"string"},"stage":{"type":"string"},"status":{"type":"string"},"editing":{"anyOf":[{"type":"object","properties":{"revision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["revision"],"additionalProperties":{}},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","kind","title","stage","status"],"additionalProperties":{}}},"required":["revision","seq","editIds","warnings","project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"revision":4,"seq":4,"editIds":["ed_0a1b2c3d4e5f6a7b8c9d","ed_1a1b2c3d4e5f6a7b8c9d"],"warnings":[],"project":{"id":"6f1d2c9a-3b7e-4f58-a0d4-9c2e7b1a5f30","kind":"story","storyFlavor":"you-decide","title":"The Vault Under the Bakery","stage":"completed","status":"completed","editing":{"enabled":false,"revision":4,"seq":4,"running":[],"rendersToday":0,"rendersPerDay":null,"prices":null},"scenes":[{"index":0,"text":"You find a door behind the ovens.","imageUrl":"https://media.autoclips.app/stickman/example/scene-0.png","videoUrl":null,"thumbnailUrl":null,"status":"done","redo":null,"durationMs":4200,"visual":null,"castIds":["you"],"cards":[]}]}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"stickman_edits_history","summary":"List the video's changes, newest first, and the videos rendered before.","description":"Lists the last 50 changes to a Story video, newest first (what each did, its status and what it was charged), the videos rendered before (newest first) and what the editor's changes were charged in all.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.edits.history","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_edit action=history","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The video (projectId from stickman_projects list or create).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The video (projectId from stickman_projects list or create).","example":"6f1d2c9a-3b7e-4f58-a0d4-9c2e7b1a5f30"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"edits":{"type":"array","items":{"type":"object","properties":{"editId":{"type":"string"},"batchId":{"description":"The batch it was sent in: a fix's fixId for a Fix this change.","anyOf":[{"type":"string"},{"type":"null"}]},"seq":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"at":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"sceneIndex":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"description":"pending, applied, failed or undone.","type":"string"},"credits":{"description":"What it was charged.","type":"number"},"costStatus":{"description":"free, pending, charged, not_charged or owed.","type":"string"},"warnings":{"type":"array","items":{"type":"string"}},"error":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["editId","batchId","seq","at","type","sceneIndex","summary","status","credits","costStatus","warnings","error"],"additionalProperties":false}},"renders":{"type":"array","items":{"type":"object","properties":{"videoUrl":{"type":"string"},"at":{"anyOf":[{"type":"string"},{"type":"null"}]},"seq":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationMs":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["videoUrl","at","seq","durationMs"],"additionalProperties":false}},"spentCredits":{"description":"What the editor's changes on this video were charged in all.","type":"number"}},"required":["edits","renders","spentCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"edits":[{"editId":"ed_2a1b2c3d4e5f6a7b8c9d","batchId":null,"seq":5,"at":"2026-10-25T10:02:00.000Z","type":"picture.redraw","sceneIndex":4,"summary":"Scene 5: drew the picture again","status":"applied","credits":31,"costStatus":"charged","warnings":[],"error":null}],"renders":[{"videoUrl":"https://media.autoclips.app/stickman/example/final.mp4","at":"2026-10-24T18:00:00.000Z","seq":0,"durationMs":58000}],"spentCredits":31}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/{projectId}/edits/paid":{"post":{"operationId":"stickman_edits_apply_paid","summary":"Make up to 6 changes that make new voice, pictures, music or clips. Answers with a job.","description":"Makes up to 6 changes that make something new on a finished Story video: a new line (the voice is recorded again), a picture changed as you describe (with up to 3 photos you added), a scene drawn again (with new staging if you like), new music, or a scene made to move. The price is the sum of each change's own line: each is charged at what it really costs when it works, never above its line, and a change that fails is not charged. Every change is checked against the video first, so one that cannot be made is refused before you approve anything. It answers with a job (status 202) that ends when every change is done; the video's editing.revision moves as each lands. Paid plans only. The changes show in the video after stickman_projects render.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.edits.apply_paid","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_edit action=apply_paid","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"baseRevision":{"description":"The editing.revision you read (stickman_projects get, include editing); an older one is refused (409 stale_revision).","type":"integer","minimum":0,"maximum":9007199254740991},"edits":{"description":"1 to 6 changes that make new voice, pictures, music or clips.","minItems":1,"maxItems":6,"type":"array","items":{"anyOf":[{"description":"Change what the narrator says in a scene (the voice is recorded again).","type":"object","properties":{"type":{"type":"string","const":"script.line"},"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"text":{"description":"The new line: 1 to 60 words.","type":"string","minLength":1,"maxLength":420}},"required":["type","sceneIndex","text"],"additionalProperties":false},{"description":"Change the scene's picture as you describe.","type":"object","properties":{"type":{"type":"string","const":"picture.edit"},"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"instruction":{"description":"What should change in the picture.","type":"string","minLength":3,"maxLength":300},"refs":{"description":"Up to 3 photos you added to draw from.","maxItems":3,"type":"array","items":{"type":"object","properties":{"uploadId":{"description":"A picture added with stickman_story upload_image.","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"kind":{"description":"A person or a thing.","type":"string","enum":["person","thing"]},"what":{"description":"What it is, in a few words.","type":"string","minLength":1,"maxLength":60}},"required":["uploadId","kind","what"],"additionalProperties":false}}},"required":["type","sceneIndex","instruction"],"additionalProperties":false},{"description":"Draw the scene's picture again.","type":"object","properties":{"type":{"type":"string","const":"picture.redraw"},"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"note":{"description":"A note for the new picture.","type":"string","maxLength":300}},"required":["type","sceneIndex"],"additionalProperties":false},{"description":"Make new music for the video.","type":"object","properties":{"type":{"type":"string","const":"music.make"},"direction":{"description":"The mood, e.g. \"slow and tense\".","type":"string","maxLength":120}},"required":["type"],"additionalProperties":false},{"description":"Draw the scene again with new staging, checked against what it must show.","type":"object","properties":{"type":{"type":"string","const":"picture.restage"},"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"prompt":{"description":"What the new picture shows, in English.","type":"string","minLength":40,"maxLength":700},"mustShow":{"description":"What the new picture must show.","minItems":1,"maxItems":3,"type":"array","items":{"description":"A yes/no question the picture must pass, in English.","type":"string","minLength":1,"maxLength":140}},"matchSceneIndex":{"description":"A nearby scene whose picture to match.","type":"integer","minimum":0,"maximum":199},"staging":{"description":"What the new picture shows. Leave a field out to keep the scene's own.","type":"object","properties":{"castIds":{"description":"Who is in the picture.","maxItems":6,"type":"array","items":{"description":"A cast id of this story (\"you\" is the viewer).","type":"string","minLength":1,"maxLength":40}},"shot":{"anyOf":[{"description":"The shot, e.g. \"close\".","type":"string","maxLength":300},{"type":"null"}]},"angle":{"anyOf":[{"description":"The camera angle.","type":"string","maxLength":300},{"type":"null"}]},"locationId":{"description":"One of the story's places.","anyOf":[{"type":"string","minLength":1,"maxLength":40},{"type":"null"}]},"conditions":{"description":"Time of day, light and weather.","anyOf":[{"type":"object","properties":{"timeOfDay":{"type":"string","enum":["dawn","day","dusk","night"]},"lighting":{"description":"The light.","type":"string","maxLength":96},"weather":{"description":"The weather.","type":"string","maxLength":40}},"additionalProperties":false},{"type":"null"}]},"propStates":{"description":"How the story's props look in this picture.","maxItems":12,"type":"array","items":{"type":"object","properties":{"propId":{"type":"string","minLength":1,"maxLength":40},"state":{"description":"How the prop looks now (\"absent\" when it is not in the shot).","type":"string","minLength":1,"maxLength":40}},"required":["propId","state"],"additionalProperties":false}},"dressing":{"anyOf":[{"description":"What else is in the set.","type":"string","maxLength":300},{"type":"null"}]},"blocking":{"anyOf":[{"description":"Who is where, one entry per person in the scene.","maxItems":6,"type":"array","items":{"type":"object","properties":{"castId":{"description":"A cast id of this story (\"you\" is the viewer).","type":"string","minLength":1,"maxLength":40},"where":{"description":"Where they are, in English, e.g. \"behind the counter\".","type":"string","maxLength":80},"side":{"description":"in (in the shot), out (out of it), door, screen.","type":"string","enum":["in","out","door","screen"]}},"required":["castId","where","side"],"additionalProperties":false}},{"type":"null"}]},"heldBy":{"description":"Whose hand holds the thing: a cast id, \"you\", or null for nobody.","anyOf":[{"type":"string","minLength":1,"maxLength":40},{"type":"null"}]}},"additionalProperties":false}},"required":["type","sceneIndex","prompt","mustShow"],"additionalProperties":false},{"description":"Make the scene move (a clip from its picture).","type":"object","properties":{"type":{"type":"string","const":"clip.make"},"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"motionNote":{"description":"What should move, in plain words.","type":"string","maxLength":200},"fix":{"description":"What was wrong with the last clip.","type":"string","maxLength":300}},"required":["type","sceneIndex"],"additionalProperties":false}]}},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"required":["baseRevision","edits"],"additionalProperties":false},"example":{"baseRevision":4,"edits":[{"type":"picture.redraw","sceneIndex":4,"note":"The vault door stands open."}]}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The video (projectId from stickman_projects list or create).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The video (projectId from stickman_projects list or create).","example":"6f1d2c9a-3b7e-4f58-a0d4-9c2e7b1a5f30"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"revision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"editIds":{"description":"One id per change started, in order.","type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"job":{"description":"Follow it with autoclips_jobs get: it succeeds with each change's outcome and credits.","anyOf":[{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},{"type":"null"}]},"approvedCredits":{"description":"What you approved for this call. Nothing is charged until each part works; the job settles it to what was really charged.","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["revision","editIds","warnings","job","approvedCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"revision":4,"editIds":["ed_2a1b2c3d4e5f6a7b8c9d"],"warnings":[],"job":{"id":"job_019a1b2c3d4e5f6a7b8c9d0e","product":"stickman","kind":"stickman.edits","resource":{"type":"project","id":"6f1d2c9a-3b7e-4f58-a0d4-9c2e7b1a5f30"},"status":"running","step":"Making 1 change","progress":0,"result":null,"error":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","finishedAt":null,"poll_after_seconds":15},"approvedCredits":45}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/{projectId}/edits/undo":{"post":{"operationId":"stickman_edits_undo","summary":"Undo the newest change, or a whole Fix this fix. It never refunds.","description":"Takes back the newest change to the video (all of it when it was sent as one batch), or, with fixId, every change one Fix this fix applied, even after later changes elsewhere. It never refunds: a paid picture, clip or track stays in the scene's takes, one change away (apply picture.take, clip.take or music.pick takeId). 409 nothing_to_undo, job_running (a change is still being made) or later_edits (a later change touched the same thing: undo that first).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.edits.undo","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_edit action=undo","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"baseRevision":{"description":"The editing.revision you read (stickman_projects get, include editing); an older one is refused (409 stale_revision).","type":"integer","minimum":0,"maximum":9007199254740991},"fixId":{"description":"The Fix this run (fixId from stickman_edit fix).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"required":["baseRevision"],"additionalProperties":false},"example":{"baseRevision":4}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The video (projectId from stickman_projects list or create).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The video (projectId from stickman_projects list or create).","example":"6f1d2c9a-3b7e-4f58-a0d4-9c2e7b1a5f30"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"revision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"undone":{"description":"What was undone.","type":"object","properties":{"editId":{"anyOf":[{"type":"string"},{"type":"null"}]},"batchId":{"anyOf":[{"type":"string"},{"type":"null"}]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"editIds":{"type":"array","items":{"type":"string"}}},"required":["editId","batchId","summary","editIds"],"additionalProperties":false},"project":{"description":"The video after the change (see stickman_projects get), with its editing state and scenes.","type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"type":"string"},"title":{"type":"string"},"stage":{"type":"string"},"status":{"type":"string"},"editing":{"anyOf":[{"type":"object","properties":{"revision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["revision"],"additionalProperties":{}},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","kind","title","stage","status"],"additionalProperties":{}}},"required":["revision","undone","project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/{projectId}/fixes":{"post":{"operationId":"stickman_fixes_create","summary":"Ask Fix this to find and plan a fix for a problem you describe. Answers with a job.","description":"Fix this: describe what is wrong in plain words, at a moment, in a scene or a few, in a screenshot you added or in the whole video. The assistant reads the video and answers with a plan of changes (each with its credits), or a question with options, or that it found nothing to change. Its reading is charged at what it really costs when it answers, never above the price; a look that fails is not charged. It answers with a job (status 202); then read the plan with fix_status and apply the steps you want with fix_apply. Up to 30 fixes a day, needs about 60 credits free, paid plans only.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.fixes.create","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_edit action=fix","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"baseRevision":{"description":"The editing.revision you read (stickman_projects get, include editing); an older one is refused (409 stale_revision).","type":"integer","minimum":0,"maximum":9007199254740991},"scope":{"description":"What to fix: a moment, a scene, a few scenes, a screenshot or the whole video.","anyOf":[{"description":"One moment of the video.","type":"object","properties":{"kind":{"type":"string","const":"moment"},"atMs":{"description":"The moment, in ms from the start of the video.","type":"integer","minimum":0,"maximum":3600000},"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199}},"required":["kind","atMs"],"additionalProperties":false},{"description":"One scene.","type":"object","properties":{"kind":{"type":"string","const":"scene"},"sceneIndex":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199}},"required":["kind","sceneIndex"],"additionalProperties":false},{"description":"A few scenes.","type":"object","properties":{"kind":{"type":"string","const":"range"},"sceneIndexes":{"description":"Up to 8 scenes.","minItems":1,"maxItems":8,"type":"array","items":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199}}},"required":["kind","sceneIndexes"],"additionalProperties":false},{"description":"What a screenshot shows.","type":"object","properties":{"kind":{"type":"string","const":"screenshot"},"uploadId":{"description":"A screenshot you added (stickman_story upload_image).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"required":["kind","uploadId"],"additionalProperties":false},{"description":"The whole video.","type":"object","properties":{"kind":{"type":"string","const":"video"}},"required":["kind"],"additionalProperties":false}]},"request":{"description":"What is wrong, in plain words (up to 600 characters). Needed unless you send a screenshot.","type":"string","maxLength":600},"screenshotUploadId":{"description":"A screenshot you added (stickman_story upload_image) that shows the problem.","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"required":["baseRevision","scope"],"additionalProperties":false},"example":{"baseRevision":4,"scope":{"kind":"scene","sceneIndex":4},"request":"The door should be open in this scene."}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The video (projectId from stickman_projects list or create).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The video (projectId from stickman_projects list or create).","example":"6f1d2c9a-3b7e-4f58-a0d4-9c2e7b1a5f30"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"fix":{"description":"The fix (fixId) and its status.","type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}},"required":["id","status"],"additionalProperties":false},"job":{"description":"Follow it with autoclips_jobs get: it succeeds when the plan (or a question) is ready.","anyOf":[{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},{"type":"null"}]},"approvedCredits":{"description":"What you approved for this call. Nothing is charged until each part works; the job settles it to what was really charged.","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["fix","job","approvedCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"fix":{"id":"er_3f9a1c7e5b2d4a6c8e0f","status":"queued"},"job":{"id":"job_019a1b2c3d4e5f6a7b8c9d0e","product":"stickman","kind":"stickman.fix","resource":{"type":"fix","id":"er_3f9a1c7e5b2d4a6c8e0f"},"status":"running","step":"Waiting to start","progress":0,"result":null,"error":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","finishedAt":null,"poll_after_seconds":15},"approvedCredits":150}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/{projectId}/next-part":{"get":{"operationId":"stickman_series_next_part_info","summary":"See what the next part of a finished part starts from: its vote, cast, settings and prices.","description":"What \"Make Part N\" starts from: the part number, the vote it ends on (its two words), the cast, the settings the next part keeps unless you change them, the prices by length and motion, the parts already made from it, idea chips, and with chapters on how it goes on (continueBy: vote, or chapter for a True Story with no vote), the planned length and whether it may be made the last part.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.series.next_part_info","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_series action=next_part_info","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"nextPart":{"type":"object","properties":{"partNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"vote":{"anyOf":[{"type":"object","properties":{"question":{"type":"string"},"a":{"type":"string"},"b":{"type":"string"}},"required":["a","b"],"additionalProperties":false},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["castId","name","masterUrl"],"additionalProperties":false}},"defaults":{"anyOf":[{"type":"object","properties":{"lengthSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pace":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"locale":{"anyOf":[{"type":"string"},{"type":"null"}]},"captions":{"type":"boolean"},"captionStyle":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"videoSpeed":{"type":"number"},"storyMotion":{"type":"string","enum":["stills","key","full"]},"music":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["lengthSeconds","voiceId","pace","language","locale","captions","captionStyle","videoSpeed","storyMotion","music"],"additionalProperties":false},{"type":"null"}]},"pasteScript":{"type":"boolean"},"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"seriesTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"parentTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"parentPartNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"children":{"type":"array","items":{"type":"object","properties":{"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["projectId","status","progress"],"additionalProperties":false}},"editsPending":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"settings":{},"quotes":{},"storySoFarCached":{"type":"boolean"},"draftStale":{"type":"boolean"},"ideaChips":{"type":"array","items":{}},"continueBy":{"description":"How this part goes on: by its vote, as the next chapter (no vote), or from a pasted script.","anyOf":[{"type":"string","enum":["vote","chapter","pasted"]},{"type":"null"}]},"plannedParts":{"description":"How many parts the series is planned to have, when set.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"finalPart":{"description":"True when the next part is the last one.","type":"boolean"},"finalPartAllowed":{"description":"Whether next_part may make it the last part (finalPart).","type":"boolean"}},"required":["partNumber","seriesId","vote","cast","defaults"],"additionalProperties":false}},"required":["nextPart"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"nextPart":{"partNumber":2,"seriesId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","vote":{"question":"Do you trust him?","a":"TRUST","b":"RUN"},"cast":[{"castId":"mara","name":"Mara","masterUrl":"https://media.autoclips.app/stickman/cast/mara.png"}],"defaults":{"lengthSeconds":90,"voiceId":"nPczCjzI2devNBz1zQrb","pace":"brisk","language":"en","locale":null,"captions":true,"captionStyle":null,"videoSpeed":1,"storyMotion":"stills","music":null},"children":[],"continueBy":"vote","plannedParts":5,"finalPart":false,"finalPartAllowed":true}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"stickman_series_next_part","summary":"Make the next part of a series from a finished part, with the winning vote. Answers with a job.","description":"Makes Part N from a finished Story part: with the winning word and its share when that part ended on a vote, or as the next chapter of a True Story (no vote). It keeps the part's settings (length, narrator, captions, music, motion while offered, your watermark and your outro) unless you send new ones; Best Clip is never kept. direction steers it; castAdd adds your own cast; script makes it from your own words; finalPart makes it the last part and plannedParts sets the series length (the writer is told \"Part N of M\"). What you approve is a spending limit: the most the run can be charged, step by step as it is made (the base when its pictures are done, each moving scene as it moves); usually much less. If the limit is higher by the time it starts, nothing starts (409 price_changed). One next part is made from a part at a time (409 part_making); the part a running series automation goes on from is the automation's (409 series_part_in_use: pause it first). It answers with a job (status 202): follow it with autoclips_jobs get. Sending the same request again with the same Idempotency-Key carries on the part it started.\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. The limit is the most Stickman video can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.series.next_part","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_series action=next_part","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vote":{"description":"The vote result of the part it goes on from: needed when that part ended on a vote (count_votes or count_pasted_votes count it), refused for a True Story chapter.","type":"object","properties":{"winner":{"description":"One of the part's two vote words, exactly as the vote shows it (any case).","type":"string","minLength":1,"maxLength":40},"percent":{"description":"The winner's share of the votes, 50 to 99 (50 is a tie you broke).","type":"integer","minimum":50,"maximum":99}},"required":["winner","percent"],"additionalProperties":false},"direction":{"description":"How you want this part to go, in a sentence (at most 300 characters).","type":"string","minLength":1,"maxLength":300},"castAdd":{"description":"Up to 3 of your cast (characterId from stickman_cast list) to add in this part; a story has at most 6 people.","maxItems":3,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"script":{"description":"Your own script for this part instead of the writer's (price it first with quote_script_part).","type":"string","minLength":1,"maxLength":2000},"scriptVote":{"description":"The vote your pasted script ends on. Leave it out for a part with no vote.","type":"object","properties":{"question":{"description":"The vote question on the end card, one short line (at most 40 characters).","type":"string","minLength":1,"maxLength":40},"a":{"description":"The first answer: one word.","type":"string","minLength":1,"maxLength":40},"b":{"description":"The second answer: one word, not the same as the first.","type":"string","minLength":1,"maxLength":40}},"required":["question","a","b"],"additionalProperties":false},"languageConfirmed":{"description":"With script: true once you confirmed it is in the series' language.","type":"boolean"},"finalPart":{"description":"True makes this the series' last part: it pays off the story and ends it (not with a pasted script).","type":"boolean"},"plannedParts":{"description":"Planned parts: How many parts a Story series is planned to have, so Part 1 is paced as the start of a longer story and the last part ends it. Needs the chapters switch (stickman.capabilities.get series.chapters). From 2 to 20 parts. Default: No set number of parts (leave it out).","type":"integer","minimum":2,"maximum":20},"lengthSeconds":{"description":"Story length: How long a Story (or a Story part) runs. It sets the base price; moving scenes are added on top.\nChoices:\n- 30 — 30 seconds: A 30-second story. (600 credits base (x your plan multiplier))\n- 40 — 40 seconds: A 40-second story. (750 credits base (x your plan multiplier))\n- 50 — 50 seconds: A 50-second story. (950 credits base (x your plan multiplier))\n- 60 — 1 minute: A 60-second story. (1100 credits base (x your plan multiplier))\n- 70 — 1.2 minutes: A 70-second story. (1250 credits base (x your plan multiplier))\n- 80 — 1.3 minutes: A 80-second story. (1400 credits base (x your plan multiplier))\n- 90 — 1.5 minutes: A 90-second story. (1550 credits base (x your plan multiplier))\n- 100 — 1.7 minutes: A 100-second story. (1700 credits base (x your plan multiplier))\n- 110 — 1.8 minutes: A 110-second story. (1850 credits base (x your plan multiplier))\n- 120 — 2 minutes: A 120-second story. (2000 credits base (x your plan multiplier))\nDefault: 90.","type":"string","enum":["30","40","50","60","70","80","90","100","110","120"]},"theme":{"description":"Text card look: The look of a Story's on-screen text cards and its end card.\nChoices:\n- night — Night: Dark card, green edge.\n- ink — Ink: Dark tiles, pink accents, paper fact cards.\n- clean — Clean: White card, black text.\nDefault: Night for You Decide, Ink for True Story (leave it out).","type":"string","enum":["night","ink","clean"]},"motion":{"description":"Story motion: How much of a Story moves. Moving scenes are paid plans only and are charged as each one is made, never above the quote's \"at most\". Story options (You Decide, True Story) need Stickman Story switched on for the account; stickman.capabilities.get says what is on right now.\nChoices:\n- stills — Stills: Pictures with camera moves; nothing is animated.\n- key — Key moments: The key moments of the story move. (118 credits a moving scene (a 5-second clip on AutoClips 1; storyMotionModel changes it), at most the quote's cap; plans: paid)\n- full — Full motion: Every picture scene moves. (118 credits a moving scene (a 5-second clip on AutoClips 1; storyMotionModel changes it), at most the quote's cap; plans: paid)\nDefault: stills.","type":"string","enum":["stills","key","full"]},"bestClip":{"description":"Up to 3 takes of each moving scene, keeping the best (every take is charged). Needs key or full motion.","type":"boolean"},"motionModel":{"description":"The AutoClips model the moving scenes are filmed with (left out: as the part it goes on from). Needs key or full motion.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd"]},"voiceId":{"description":"A narrator for this part instead of the series narrator (left out: as the part it goes on from): a house voice or one of your cloned voices.","type":"string","pattern":"^[A-Za-z0-9]{8,64}$"},"captions":{"description":"Captions on or off (left out: as the part it goes on from).","type":"boolean"},"captionStyle":{"description":"The caption look. Leave a key out to keep the format's own.","type":"object","properties":{"highlightStyle":{"description":"Caption look: How the spoken words appear on screen (captionStyle.highlightStyle). The same looks every AutoClips format uses.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionStyle) to see them all.\nDefault: The format's own look (leave it out).","type":"string","enum":["classic","color-only","scale-up","typewriter","progressive","karaoke","bounce","outline","background","shadow-pop","pop-color","neon","underline","gradient","boxed","glow"]},"fontFamily":{"description":"Caption font: The lettering of the captions (captionStyle.fontFamily).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionFont) to see them all.\nDefault: The caption look's own font (leave it out).","type":"string","enum":["Montserrat","BebasNeue","Anton","LeagueSpartan"]},"position":{"description":"Caption position: Where the captions sit (captionStyle.position).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionPosition) to see them all.\nDefault: The format's own position (leave it out).","type":"string","enum":["top","upper-third","center","lower-third","bottom"]},"positionY":{"description":"Where the captions sit, 0 (top) to 100 (bottom); wins over position.","type":"number","minimum":0,"maximum":100},"groupSize":{"description":"Words at a time: How many words the captions show at once (captionStyle.groupSize, sent as a number).\nChoices:\n- 2 — 2 words: Punchy. Reads fastest.\n- 3 — 3 words: The default.\n- 4 — 4 words: Calmer, fewer changes.\nDefault: The caption look's own size (leave it out).","type":"string","enum":["2","3","4"]},"fontSize":{"description":"Caption size, 28 to 110.","type":"integer","minimum":28,"maximum":110},"color":{"description":"Caption colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"highlightColor":{"description":"The spoken word's colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"showBackground":{"description":"A box behind the captions.","type":"boolean"},"backgroundOpacity":{"description":"How solid that box is, 0 to 1.","type":"number","minimum":0,"maximum":1}},"additionalProperties":false},"videoSpeed":{"description":"Video speed: How fast the finished video plays, from 1x to 3x in steps of 0.1. The page's quick picks: 1x, 1.1x, 1.2x, 1.3x, 1.5x, 2x, 3x. Free: it changes no price. From 1 to 3 x, in steps of 0.1. Default: 1.","type":"number","minimum":1,"maximum":3,"multipleOf":0.1},"musicTrackId":{"title":"Music (Stickman videos (Explainer, Skit, Story) option musicTrack)","description":"Music: A music track by id: \"none\" (no music, when an Explainer or Skit is made; a render refuses it, since a render always keeps the video's music: turn a Story's music off with the edit music.none), a track of the music library, or a Story music bed (meta.kind \"bed\"). Links are never taken: the id picks the track.\nChoices: one of 232 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=musicTrack) to see them all.\nDefault: The format's default (Story: the series bed) (leave it out).","type":"string"},"watermarkType":{"description":"Watermark: Your text or picture on the video. Every plan.\nChoices:\n- none — None: No watermark.\n- text — Text: watermarkText.\n- image — Picture: watermarkMediaId.\nDefault: none.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"Text: The words. Default: No text (leave it out).","type":"string","minLength":1,"maxLength":50},"watermarkTextColor":{"description":"Text colour: #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundColor":{"description":"Box colour: #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundOpacity":{"description":"Box: Box, 0 (none) to 1. From 0 to 1, in steps of 0.01. Default: 0.5.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"watermarkMediaId":{"description":"A picture from autoclips_media, by id. Default: No picture (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"watermarkImageOpacity":{"description":"Picture opacity: 0.3 to 1. From 0.3 to 1, in steps of 0.01. Default: 0.7.","type":"number","minimum":0.3,"maximum":1,"multipleOf":0.01},"watermarkVerticalPosition":{"description":"Height: Percent from the top. From 10 to 90 percent. Default: 85.","type":"integer","minimum":10,"maximum":90},"watermarkHorizontalPosition":{"description":"Across: Percent from the left. From 5 to 95 percent. Default: 85.","type":"integer","minimum":5,"maximum":95},"watermarkScale":{"description":"Size: 1 is normal. From 0.5 to 3, in steps of 0.01. Default: 1.","type":"number","minimum":0.5,"maximum":3,"multipleOf":0.01},"watermarkStartSeconds":{"description":"From: Seconds into the video it appears. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"watermarkEndSeconds":{"description":"Until: Seconds into the video it goes; 0 = to the end. At least 0.5 s after the start. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"outroId":{"description":"Outro: An end card from autoclips_outros, after the last scene. Paid plans (free: plan_required). \"none\" = no outro. A Story's own end card still closes the story; the outro plays after it. Default: No outro (leave it out).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"additionalProperties":false},"example":{"vote":{"winner":"TRUST","percent":63}}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"type":"string","enum":["explainer","skit","story"]},"storyFlavor":{"anyOf":[{"type":"string","enum":["you-decide","true-story"]},{"type":"null"}]},"title":{"type":"string"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"type":"string","enum":["queued","writing","voicing","drawing","filming","transcribing","preview_ready","rendering","completed","failed"]},"status":{"type":"string"},"progress":{"type":"number"},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","status"],"additionalProperties":false},"thumbnail":{"anyOf":[{"type":"object","properties":{"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","url"],"additionalProperties":false},{"type":"null"}]},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"parentProjectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextPartNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextPartProjectId":{"type":"string"}},"required":["seriesId","partNumber","parentProjectId"],"additionalProperties":false},{"type":"null"}]},"automation":{"anyOf":[{"type":"object","properties":{"automationId":{"type":"string"}},"required":["automationId"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"currentStep":{"type":"string"},"error":{"anyOf":[{"type":"object","properties":{"step":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"type":"string"}},"required":["step","message"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"used":{"type":"number"},"estimated":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["used","estimated"],"additionalProperties":false},"story":{"type":"object","properties":{"vote":{"anyOf":[{"type":"object","properties":{"question":{"type":"string"},"a":{"type":"string"},"b":{"type":"string"}},"required":["a","b"],"additionalProperties":false},{"type":"null"}]},"voteResult":{"anyOf":[{"type":"object","properties":{"winner":{"type":"string"},"loser":{"anyOf":[{"type":"string"},{"type":"null"}]},"percent":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["winner","loser","percent"],"additionalProperties":false},{"type":"null"}]},"ending":{"anyOf":[{"type":"string","enum":["vote","follow"]},{"type":"null"}]},"seriesTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"chapter":{"type":"boolean"},"finalPart":{"type":"boolean"},"plannedParts":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["vote","voteResult","ending","seriesTitle","chapter","finalPart","plannedParts"],"additionalProperties":false}},"required":["id","kind","storyFlavor","title","topic","stage","status","progress","video","thumbnail","series","automation","createdAt","updatedAt","appUrl","currentStep","error","credits"],"additionalProperties":false},"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"continued":{"description":"True when this carried on a part an earlier try of the same request already started.","type":"boolean"}},"required":["project","job","continued"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"c4a2d3e5-6f70-4b8c-9dae-1f2a3b4c5d6e","kind":"story","storyFlavor":"you-decide","title":"The Stranger at the Door","topic":null,"stage":"queued","status":"queued","progress":3,"video":{"url":null,"status":null},"thumbnail":null,"series":{"seriesId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","partNumber":2,"parentProjectId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},"automation":null,"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z","appUrl":"https://app.autoclips.app/stickman?sessionId=c4a2d3e5-6f70-4b8c-9dae-1f2a3b4c5d6e","currentStep":"Waiting to start","error":null,"credits":{"used":0,"estimated":null},"story":{"vote":null,"voteResult":{"winner":"TRUST","loser":"RUN","percent":63},"ending":"vote","seriesTitle":"The Stranger","chapter":false,"finalPart":false,"plannedParts":5}},"job":{"id":"job_019a1b2c3d4e5f60718293a4","product":"stickman","kind":"stickman.video","resource":{"type":"project","id":"c4a2d3e5-6f70-4b8c-9dae-1f2a3b4c5d6e"},"status":"queued","step":"Writing the script","progress":null,"result":null,"error":null,"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z","finishedAt":null,"poll_after_seconds":15},"continued":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/{projectId}/next-part/quote":{"post":{"operationId":"stickman_series_quote_script_part","summary":"Measure and price your own script as the next part, without making it.","description":"Reads a script you wrote for the next part with the series' own narrator (or the voiceId you name), pace and language, and says how long it runs and what it would cost. Nothing is made or stored. Make it with next_part (script, and the same voiceId).\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.series.quote_script_part","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_series action=quote_script_part","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"script":{"description":"Your script for the next part, as it is read aloud (at most 2,000 characters).","type":"string","minLength":1,"maxLength":2000},"vote":{"description":"The vote your pasted script ends on. Leave it out for a part with no vote.","type":"object","properties":{"question":{"description":"The vote question on the end card, one short line (at most 40 characters).","type":"string","minLength":1,"maxLength":40},"a":{"description":"The first answer: one word.","type":"string","minLength":1,"maxLength":40},"b":{"description":"The second answer: one word, not the same as the first.","type":"string","minLength":1,"maxLength":40}},"required":["question","a","b"],"additionalProperties":false},"languageConfirmed":{"description":"True once you confirmed the script is in the series' language when it was asked.","type":"boolean"},"voiceId":{"description":"A narrator for this part instead of the series narrator: a house voice or one of your cloned voices.","type":"string","pattern":"^[A-Za-z0-9]{8,64}$"}},"required":["script"],"additionalProperties":false},"example":{"script":"You open the door. He smiles, and the lights go out."}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"partNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"script":{"type":"object","properties":{"lines":{"type":"array","items":{}},"seconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"videoSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"label":{"anyOf":[{"type":"number"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pace":{"anyOf":[{"type":"string"},{"type":"null"}]},"flavor":{"anyOf":[{"type":"string"},{"type":"null"}]},"vote":{"anyOf":[{},{"type":"null"}]}},"required":["lines","seconds","videoSeconds","label","language","voiceId","pace","flavor","vote"],"additionalProperties":false},"quote":{}},"required":["partNumber","script","quote"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"partNumber":2,"script":{"lines":["You open the door.","He smiles, and the lights go out."],"seconds":6,"videoSeconds":30,"label":30,"language":"en","voiceId":"nPczCjzI2devNBz1zQrb","pace":"brisk","flavor":"you-decide","vote":null},"quote":{"video":{"atMost":420}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/{projectId}/render":{"post":{"operationId":"stickman_projects_render","summary":"Render a made video again, with your latest changes or another music track. Answers with a job.","description":"Renders a video that is ready (or already rendered) again, with its latest changes and, if you pick one, another music track (musicTrackId; leaving it out keeps the music it was made with; \"none\" is refused: a render never drops the music, turn a Story's music off with the edit music.none first). The render itself is not charged; a video that has no cover picture yet gets one when the render is done, and that cover is the price (0 when it has one). A video can be rendered a limited number of times a day. Answers at once with a job (status 202); follow it with autoclips_jobs get. It cannot run while the video is still being made, rendering, or changing.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.projects.render","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_projects action=render","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"musicTrackId":{"title":"Music (Stickman videos (Explainer, Skit, Story) option musicTrack)","description":"Music: A music track by id: \"none\" (no music, when an Explainer or Skit is made; a render refuses it, since a render always keeps the video's music: turn a Story's music off with the edit music.none), a track of the music library, or a Story music bed (meta.kind \"bed\"). Links are never taken: the id picks the track.\nChoices: one of 232 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=musicTrack) to see them all.\nDefault: The format's default (Story: the series bed) (leave it out).","type":"string"},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The video (projectId from stickman_projects list or create).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The video (projectId from stickman_projects list or create).","example":"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"description":"The video's projectId.","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"explainer, skit or story.","type":"string","enum":["explainer","skit","story"]},"storyFlavor":{"description":"A Story's kind (You Decide or True Story); null for others.","anyOf":[{"type":"string","enum":["you-decide","true-story"]},{"type":"null"}]},"title":{"type":"string"},"topic":{"description":"What it was asked to be about.","anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"description":"Where it is: queued, writing, voicing, drawing, filming, transcribing, preview_ready, rendering, completed or failed.","type":"string","enum":["queued","writing","voicing","drawing","filming","transcribing","preview_ready","rendering","completed","failed"]},"status":{"description":"The raw status word.","type":"string"},"progress":{"type":"integer","minimum":0,"maximum":100},"video":{"description":"The finished video, once rendered.","type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","status"],"additionalProperties":false},"thumbnail":{"anyOf":[{"type":"object","properties":{"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","url"],"additionalProperties":false},{"type":"null"}]},"series":{"description":"A Story part's series, or null.","anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"parentProjectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextPartNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextPartProjectId":{"type":"string"}},"required":["seriesId","partNumber","parentProjectId"],"additionalProperties":false},{"type":"null"}]},"automation":{"description":"The automation that made it, or null.","anyOf":[{"type":"object","properties":{"automationId":{"type":"string"}},"required":["automationId"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"description":"Open it in the app.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","kind","storyFlavor","title","topic","stage","status","progress","video","thumbnail","series","automation","createdAt","updatedAt","appUrl"],"additionalProperties":false},"job":{"description":"Follow it with autoclips_jobs get. It succeeds with result.videoUrl.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false}},"required":["project","job"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f","kind":"explainer","storyFlavor":null,"title":"Sell Air From Famous Cities","topic":"A deadpan business plan for bottling plain air from famous cities","stage":"rendering","status":"rendering","progress":95,"video":{"url":"https://media.autoclips.app/stickman/videos/example.mp4","status":"completed"},"thumbnail":{"status":"ready","url":"https://media.autoclips.app/stickman/scenes/example-1.png"},"series":null,"automation":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","appUrl":"https://app.autoclips.app/stickman?sessionId=6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"},"job":{"id":"job_0199a2b3c4d5e6f708192a3b","product":"stickman","kind":"stickman.render","resource":{"type":"project","id":"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"},"status":"running","step":"Rendering the video","progress":0,"result":null,"error":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","finishedAt":null,"poll_after_seconds":10}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/{projectId}/render/cancel":{"post":{"operationId":"stickman_projects_cancel_render","summary":"Stop a Story's render that is under way or stuck. The video goes back to the one it had.","description":"Stops a Story's render: an update (stickman_projects render or the editor's Update video) goes back to the video it already had, unchanged; its first render goes back to ready to render. Free, and nothing is lost: render it again with stickman_projects render when you are ready. When nothing is rendering it changes nothing and answers cancelled false. Only a Story's render can be stopped (an Explainer's or a Skit's finishes by itself in a few minutes), and not the first render of a video an automation is making.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.projects.cancel_render","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_projects action=cancel_render","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The video (projectId from stickman_projects list or create).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The video (projectId from stickman_projects list or create).","example":"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"cancelled":{"description":"true when a render was stopped; false when nothing was rendering (it had just finished or failed).","type":"boolean"},"project":{"type":"object","properties":{"id":{"description":"The video's projectId.","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"explainer, skit or story.","type":"string","enum":["explainer","skit","story"]},"storyFlavor":{"description":"A Story's kind (You Decide or True Story); null for others.","anyOf":[{"type":"string","enum":["you-decide","true-story"]},{"type":"null"}]},"title":{"type":"string"},"topic":{"description":"What it was asked to be about.","anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"description":"Where it is: queued, writing, voicing, drawing, filming, transcribing, preview_ready, rendering, completed or failed.","type":"string","enum":["queued","writing","voicing","drawing","filming","transcribing","preview_ready","rendering","completed","failed"]},"status":{"description":"The raw status word.","type":"string"},"progress":{"type":"integer","minimum":0,"maximum":100},"video":{"description":"The finished video, once rendered.","type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","status"],"additionalProperties":false},"thumbnail":{"anyOf":[{"type":"object","properties":{"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","url"],"additionalProperties":false},{"type":"null"}]},"series":{"description":"A Story part's series, or null.","anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"parentProjectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextPartNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextPartProjectId":{"type":"string"}},"required":["seriesId","partNumber","parentProjectId"],"additionalProperties":false},{"type":"null"}]},"automation":{"description":"The automation that made it, or null.","anyOf":[{"type":"object","properties":{"automationId":{"type":"string"}},"required":["automationId"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"description":"Open it in the app.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","kind","storyFlavor","title","topic","stage","status","progress","video","thumbnail","series","automation","createdAt","updatedAt","appUrl"],"additionalProperties":false}},"required":["cancelled","project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"cancelled":true,"project":{"id":"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f","kind":"story","storyFlavor":"you-decide","title":"Sell Air From Famous Cities","topic":"A deadpan business plan for bottling plain air from famous cities","stage":"completed","status":"completed","progress":100,"video":{"url":"https://media.autoclips.app/stickman/videos/example.mp4","status":"completed"},"thumbnail":{"status":"ready","url":"https://media.autoclips.app/stickman/scenes/example-1.png"},"series":null,"automation":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","appUrl":"https://app.autoclips.app/stickman?sessionId=6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/{projectId}/resume":{"post":{"operationId":"stickman_projects_resume","summary":"Carry on a video that stopped, from where it stopped. Paid: you approve the rest of its spending limit.","description":"Carries on a video that stopped with a problem, from the step it stopped at: steps that finished are kept and never charged again. What you approve is the rest of the video's spending limit, the most the run can be charged; each step is charged as it is made, usually less. A video can be carried on a limited number of times a day. A video an automation made cannot be carried on here: its automation makes that part again at its next run. Answers at once with a job (status 202).\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. The limit is the most Stickman video can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.projects.resume","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_projects action=resume","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The video (projectId from stickman_projects list or create).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The video (projectId from stickman_projects list or create).","example":"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"description":"The video's projectId.","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"explainer, skit or story.","type":"string","enum":["explainer","skit","story"]},"storyFlavor":{"description":"A Story's kind (You Decide or True Story); null for others.","anyOf":[{"type":"string","enum":["you-decide","true-story"]},{"type":"null"}]},"title":{"type":"string"},"topic":{"description":"What it was asked to be about.","anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"description":"Where it is: queued, writing, voicing, drawing, filming, transcribing, preview_ready, rendering, completed or failed.","type":"string","enum":["queued","writing","voicing","drawing","filming","transcribing","preview_ready","rendering","completed","failed"]},"status":{"description":"The raw status word.","type":"string"},"progress":{"type":"integer","minimum":0,"maximum":100},"video":{"description":"The finished video, once rendered.","type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","status"],"additionalProperties":false},"thumbnail":{"anyOf":[{"type":"object","properties":{"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","url"],"additionalProperties":false},{"type":"null"}]},"series":{"description":"A Story part's series, or null.","anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"parentProjectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextPartNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextPartProjectId":{"type":"string"}},"required":["seriesId","partNumber","parentProjectId"],"additionalProperties":false},{"type":"null"}]},"automation":{"description":"The automation that made it, or null.","anyOf":[{"type":"object","properties":{"automationId":{"type":"string"}},"required":["automationId"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"description":"Open it in the app.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","kind","storyFlavor","title","topic","stage","status","progress","video","thumbnail","series","automation","createdAt","updatedAt","appUrl"],"additionalProperties":false},"job":{"description":"Follow it with autoclips_jobs get. It succeeds with result.videoUrl.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"approvedCredits":{"description":"The rest of the spending limit you approved.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","job","approvedCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f","kind":"explainer","storyFlavor":null,"title":"Sell Air From Famous Cities","topic":"A deadpan business plan for bottling plain air from famous cities","stage":"drawing","status":"generating-keyframes","progress":45,"video":{"url":null,"status":"idle"},"thumbnail":null,"series":null,"automation":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","appUrl":"https://app.autoclips.app/stickman?sessionId=6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"},"job":{"id":"job_0199a2b3c4d5e6f708192a3b","product":"stickman","kind":"stickman.video","resource":{"type":"project","id":"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"},"status":"running","step":"Drawing the scenes","progress":45,"result":null,"error":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","finishedAt":null,"poll_after_seconds":10},"approvedCredits":20}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/{projectId}/scenes/{sceneIndex}/clip":{"post":{"operationId":"stickman_scenes_redo_clip","summary":"Make one moving scene's clip again. Answers with a job to follow.","description":"Makes the scene's clip again from its picture (a Skit scene with its lines). Only moving scenes have a clip: every scene of a Full Motion explainer, the hero scenes of an Enhanced one, every Skit scene. It is charged only when the new clip is made, at the model that made it (the price shown covers its backup too). Answers 202 with a job.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.scenes.redo_clip","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_finish action=redo_clip","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The video (projectId from stickman_projects list or create).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The video (projectId from stickman_projects list or create).","example":"6b1f0e2a-4c3d-4e5f-9a8b-7c6d5e4f3a2b"},{"name":"sceneIndex","in":"path","required":true,"schema":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"description":"Scene index (scenes[].index, from 0; not its number).","example":0},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"sceneIndex":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"job":{"description":"Follow it with autoclips_jobs get (or GET /v1/jobs/{id}). Its result has the new clip when it is done; a clip that is not made is not charged.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"approvedCredits":{"description":"The most this redo is charged, only when the new clip is made.","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["projectId","sceneIndex","job","approvedCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"6b1f0e2a-4c3d-4e5f-9a8b-7c6d5e4f3a2b","sceneIndex":0,"job":{"id":"job_019a1b2c3d4e5f6a7b8c9d0e","product":"stickman","kind":"stickman.redo","resource":{"type":"scene","id":"6b1f0e2a-4c3d-4e5f-9a8b-7c6d5e4f3a2b:0"},"status":"running","step":"Making the clip again","progress":null,"result":null,"error":null,"createdAt":"2026-10-21T10:05:00.000Z","updatedAt":"2026-10-21T10:05:00.000Z","finishedAt":null,"poll_after_seconds":10},"approvedCredits":805}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/{projectId}/scenes/{sceneIndex}/picture":{"post":{"operationId":"stickman_scenes_redo_picture","summary":"Draw one scene's picture again. Answers with a job to follow.","description":"Draws the scene's picture again from the same idea, in the video's look (a Story scene keeps its cast). It is charged only when the new picture is made; a scene that had a clip loses it (the clip was made from the old picture): make it again with redo_clip. Answers 202 with a job.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.scenes.redo_picture","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_finish action=redo_picture","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The video (projectId from stickman_projects list or create).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The video (projectId from stickman_projects list or create).","example":"6b1f0e2a-4c3d-4e5f-9a8b-7c6d5e4f3a2b"},{"name":"sceneIndex","in":"path","required":true,"schema":{"description":"Scene index (scenes[].index, from 0; not its number).","type":"integer","minimum":0,"maximum":199},"description":"Scene index (scenes[].index, from 0; not its number).","example":2},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"sceneIndex":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"job":{"description":"Follow it with autoclips_jobs get (or GET /v1/jobs/{id}). Its result has the new picture when it is done; a picture that is not made is not charged.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"approvedCredits":{"description":"The most this redo is charged, only when the new picture is made.","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["projectId","sceneIndex","job","approvedCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"6b1f0e2a-4c3d-4e5f-9a8b-7c6d5e4f3a2b","sceneIndex":2,"job":{"id":"job_019a1b2c3d4e5f6a7b8c9d0e","product":"stickman","kind":"stickman.redo","resource":{"type":"scene","id":"6b1f0e2a-4c3d-4e5f-9a8b-7c6d5e4f3a2b:2"},"status":"running","step":"Drawing the picture again","progress":null,"result":null,"error":null,"createdAt":"2026-10-21T10:00:00.000Z","updatedAt":"2026-10-21T10:00:00.000Z","finishedAt":null,"poll_after_seconds":10},"approvedCredits":50}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/{projectId}/story-so-far":{"post":{"operationId":"stickman_series_story_so_far","summary":"Read the story so far that the next part is written from, building it when it is missing.","description":"The story so far after a finished part: a synopsis, what happened, the open questions, who knows what, where everyone is, how it ends, plus your saved changes (draft) and whether they were made on an older version. Building it reads each part that has no recap yet (small, at our cost); refresh true reads the part again (60 a day). Counts toward the free-AI daily limit, given back when it came from what was already read. Needs series pages to be switched on.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.series.story_so_far","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_series action=story_so_far","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"refresh":{"description":"True reads the part again instead of the saved recap (at most 60 a day).","type":"boolean"}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"storySoFar":{"anyOf":[{"description":"The story so far: its editable keys, as plain data.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"draft":{"anyOf":[{"description":"Your saved changes, which the next part starts from.","type":"object","properties":{"savedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"storySoFar":{"anyOf":[{"description":"The story so far: its editable keys, as plain data.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["savedAt","storySoFar"],"additionalProperties":false},{"type":"null"}]},"draftStale":{"description":"True when your changes were made on an older story so far.","type":"boolean"},"editsPending":{"description":"Changes to the part's video not rendered yet.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"built":{"description":"cache (already read), model (just read) or fallback (made without the recap helper).","type":"string","enum":["cache","model","fallback"]},"building":{"description":"True when another call is building it right now: this is the saved one.","type":"boolean"}},"required":["storySoFar","draft","draftStale","editsPending","built","building"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"storySoFar":{"seriesTitle":"The Stranger","premiseNow":"You let a stranger into your house.","synopsis":"A stranger knocked at midnight. You let him in.","rules":["Keep it funny"]},"draft":null,"draftStale":false,"editsPending":0,"built":"cache","building":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"stickman_series_update_story_so_far","summary":"Save your changes to the story so far; the next part is written from them.","description":"Saves your version of the story so far on the part (read it first with story_so_far, change what you want, send it back). The next part made from this part starts from it. Lists and texts have the same limits as the story so far itself. Needs series pages to be switched on.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.series.update_story_so_far","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_series action=update_story_so_far","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"storySoFar":{"description":"The story so far with your changes: send the keys you change (read it first with story_so_far).","type":"object","properties":{"seriesTitle":{"description":"The series name (at most 60 characters).","type":"string","maxLength":60},"premiseNow":{"description":"Where the story stands now, one line (at most 100 characters).","type":"string","maxLength":100},"synopsis":{"description":"The story so far in a few sentences (at most 900 characters).","type":"string","maxLength":900},"events":{"description":"What happened, in order (at most 40).","maxItems":40,"type":"array","items":{"type":"object","properties":{"id":{"description":"The event's id, as the story so far gave it (e1, e2, ...).","type":"string","pattern":"^e\\d{1,4}$"},"part":{"description":"The part it happened in.","type":"integer","minimum":1,"maximum":9007199254740991},"text":{"description":"What happened (at most 160 characters).","type":"string","maxLength":160},"pinned":{"description":"Keep it even when the list is full.","type":"boolean"}},"required":["id","part","text"],"additionalProperties":false}},"threads":{"description":"The open questions the story carries (at most 40).","maxItems":40,"type":"array","items":{"type":"object","properties":{"id":{"description":"The open question's id (t1, t2, ...).","type":"string","pattern":"^t\\d{1,4}$"},"part":{"description":"The part that opened it.","type":"integer","minimum":1,"maximum":9007199254740991},"question":{"description":"The open question (at most 140 characters).","type":"string","maxLength":140},"status":{"description":"open, or answered.","type":"string","enum":["open","answered"]},"answeredIn":{"description":"The part that answered it.","anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"null"}]}},"required":["id","part","question","status"],"additionalProperties":false}},"knows":{"description":"Who knows what (at most 8).","maxItems":8,"type":"array","items":{"type":"object","properties":{"secret":{"description":"A secret (at most 140 characters).","type":"string","maxLength":140},"who":{"description":"The cast ids of the people who know it.","maxItems":8,"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,23}$"}},"viewerKnows":{"description":"Whether the viewer knows it too (default true).","type":"boolean"}},"required":["secret","who"],"additionalProperties":false}},"sides":{"description":"Whose side each person is on.","maxItems":8,"type":"array","items":{"type":"object","properties":{"castId":{"description":"The cast member.","type":"string","pattern":"^[a-z][a-z0-9-]{1,23}$"},"tag":{"description":"Whose side they are on, in a few words (at most 60 characters).","type":"string","maxLength":60},"cardRole":{"description":"Their role on a text card (at most 24 characters).","anyOf":[{"type":"string","maxLength":24},{"type":"null"}]},"note":{"description":"A note about them (at most 100 characters).","anyOf":[{"type":"string","maxLength":100},{"type":"null"}]}},"required":["castId","tag"],"additionalProperties":false}},"meters":{"description":"Up to 3 running counts the story shows (money, days left).","maxItems":3,"type":"array","items":{"type":"object","properties":{"id":{"description":"The meter's id.","type":"string","minLength":1,"maxLength":24},"label":{"description":"Its label (at most 24 characters).","type":"string","maxLength":24},"format":{"description":"How its value reads (text by default).","type":"string","maxLength":12},"value":{"description":"Its value: a number or a short text.","anyOf":[{"anyOf":[{"type":"number"},{"type":"string","maxLength":24}]},{"type":"null"}]}},"required":["id","label","value"],"additionalProperties":false}},"props":{"description":"The props the story carries and their state (at most 8).","maxItems":8,"type":"array","items":{"type":"object","properties":{"propId":{"description":"The prop's id.","type":"string","pattern":"^[a-z][a-z0-9-]{1,23}$"},"name":{"description":"Its name (at most 30 characters).","type":"string","maxLength":30},"state":{"description":"Its state now (at most 40 characters).","type":"string","maxLength":40}},"required":["propId","state"],"additionalProperties":false}},"positions":{"description":"Where each person is when the part ends (at most 8).","maxItems":8,"type":"array","items":{"type":"object","properties":{"castId":{"description":"The cast member.","type":"string","pattern":"^[a-z][a-z0-9-]{1,23}$"},"where":{"description":"Where they are when the part ends, in English (at most 80 characters).","type":"string","maxLength":80},"side":{"description":"Inside, outside or at the door.","anyOf":[{"type":"string","enum":["in","out","door"]},{"type":"null"}]},"holding":{"description":"What they hold (at most 40 characters).","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"unclear":{"description":"True when it is not clear where they are (a quick check with two readings).","type":"boolean"},"options":{"description":"The two readings of an unclear spot.","anyOf":[{"minItems":2,"maxItems":2,"type":"array","items":{"type":"string","maxLength":80}},{"type":"null"}]},"why":{"description":"Why it is unclear (at most 120 characters).","anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"locationId":{"description":"The place that spot is at.","type":"string","pattern":"^[a-z][a-z0-9-]{1,23}$"}},"required":["castId","where"],"additionalProperties":false}},"endsAt":{"description":"Where the part ends.","anyOf":[{"type":"object","properties":{"locationId":{"description":"The place the part ends at.","anyOf":[{"type":"string","pattern":"^[a-z][a-z0-9-]{1,23}$"},{"type":"null"}]},"placeName":{"description":"Its name (at most 40 characters).","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"conditions":{"description":"The time of day, light and weather.","anyOf":[{"type":"object","properties":{"timeOfDay":{"description":"dawn, day, dusk or night.","anyOf":[{"type":"string","enum":["dawn","day","dusk","night"]},{"type":"null"}]},"lighting":{"description":"The light (at most 96 characters).","anyOf":[{"type":"string","maxLength":96},{"type":"null"}]},"weather":{"description":"The weather (at most 40 characters).","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false},{"type":"null"}]},"rules":{"description":"Rules the story keeps (at most 8, 100 characters each).","maxItems":8,"type":"array","items":{"type":"string","maxLength":100}},"cliffhanger":{"description":"How the part ends.","type":"object","properties":{"question":{"description":"The question it ends on (at most 160 characters).","type":"string","maxLength":160},"lastLine":{"description":"Its last line (at most 200 characters).","type":"string","maxLength":200}},"additionalProperties":false},"issues":{"description":"Problems to fix in the next part (at most 3).","maxItems":3,"type":"array","items":{"type":"string","maxLength":200}}},"additionalProperties":false}},"required":["storySoFar"],"additionalProperties":false},"example":{"storySoFar":{"premiseNow":"You trusted the stranger, and he knows your name."}}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"draft":{"anyOf":[{"description":"Your saved changes, which the next part starts from.","type":"object","properties":{"savedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"storySoFar":{"anyOf":[{"description":"The story so far: its editable keys, as plain data.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["savedAt","storySoFar"],"additionalProperties":false},{"type":"null"}]}},"required":["draft"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"draft":{"savedAt":"2026-10-25T12:00:00.000Z","storySoFar":{"seriesTitle":"The Stranger","premiseNow":"You trusted the stranger, and he knows your name.","synopsis":"A stranger knocked at midnight. You let him in.","rules":["Keep it funny"]}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/{projectId}/story-so-far/reset":{"post":{"operationId":"stickman_series_reset_story_so_far","summary":"Drop your changes to the story so far and go back to what the videos show.","description":"Removes your saved changes to the story so far of a part: the next part starts from what the videos show again. Needs series pages to be switched on.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.series.reset_story_so_far","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_series action=reset_story_so_far","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"storySoFar":{"anyOf":[{"description":"The story so far: its editable keys, as plain data.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["storySoFar"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"storySoFar":{"seriesTitle":"The Stranger","premiseNow":"You let a stranger into your house.","synopsis":"A stranger knocked at midnight. You let him in.","rules":["Keep it funny"]}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/{projectId}/thumbnail":{"get":{"operationId":"stickman_thumbnails_get","summary":"See a Stickman video's cover picture, the words it gets by default and the word limits.","description":"The cover picture a video is posted with: its state, its link (the file itself), its words, and the words a new cover gets by default (a Story's is \"PART n\" over its title). credits is what a new cover picture costs.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.thumbnails.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_finish action=thumbnail","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The video (projectId from stickman_projects list or create).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The video (projectId from stickman_projects list or create).","example":"6b1f0e2a-4c3d-4e5f-9a8b-7c6d5e4f3a2b"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"thumbnail":{"description":"The cover, or null when the video has none yet.","anyOf":[{"type":"object","properties":{"status":{"description":"drawing, writing, ready or failed.","anyOf":[{"type":"string"},{"type":"null"}]},"url":{"description":"The cover picture (a JPEG), once made. It is the file itself: download it from this link.","anyOf":[{"type":"string"},{"type":"null"}]},"topLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"idea":{"description":"What the picture was asked to show, when you said.","anyOf":[{"type":"string"},{"type":"null"}]},"error":{"description":"Why the last try failed, in plain words.","anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","url","topLine","title","idea","error","updatedAt"],"additionalProperties":false},{"type":"null"}]},"defaults":{"description":"The words a new cover gets when you send none.","type":"object","properties":{"topLine":{"type":"string"},"title":{"type":"string"}},"required":["topLine","title"],"additionalProperties":false},"credits":{"description":"What a new cover picture costs (changing its words is not charged).","type":"integer","minimum":0,"maximum":9007199254740991},"limits":{"description":"The most characters each line and the picture idea may have.","type":"object","properties":{"topLine":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"title":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"idea":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["topLine","title","idea"],"additionalProperties":false}},"required":["thumbnail","defaults","credits","limits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"thumbnail":{"status":"ready","url":"https://media.autoclips.app/stickman/6b1f0e2a/thumbnail-a1b2c3.jpg","topLine":"PART 2","title":"THE BAG ON THE BACK SEAT","idea":null,"error":null,"updatedAt":"2026-10-21T10:10:00.000Z"},"defaults":{"topLine":"PART 2","title":"The Bag on the Back Seat"},"credits":20,"limits":{"topLine":24,"title":48,"idea":300}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"stickman_thumbnails_create","summary":"Make a new cover picture for a Stickman video, with its words. Answers with a job to follow.","description":"Draws a new cover picture for the video and lays its words on it: a short top line (up to 24 characters) over a big title (up to 48). Words you leave out are the video's defaults (thumbnail shows them). It is charged only when the cover is made, and every later post of the video carries it. One cover at a time per video. Answers 202 with a job.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.thumbnails.create","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_finish action=make_thumbnail","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"topLine":{"description":"The cover's short top line, up to 24 characters (a Story's is \"PART 2\"); \"\" leaves it off.","type":"string","maxLength":24},"title":{"description":"The cover's title in big letters, up to 48 characters.","type":"string","minLength":1,"maxLength":48},"idea":{"description":"What the cover picture should show, in your own words (up to 300 characters). Leave it out for a picture from the video's story.","type":"string","minLength":1,"maxLength":300},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{"title":"THE BAG ON THE BACK SEAT","idea":"The stickman staring at a black bag on a car's back seat at night"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The video (projectId from stickman_projects list or create).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The video (projectId from stickman_projects list or create).","example":"6b1f0e2a-4c3d-4e5f-9a8b-7c6d5e4f3a2b"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"job":{"description":"Follow it with autoclips_jobs get (or GET /v1/jobs/{id}). Its result has the new cover when it is done; a cover that is not made is not charged.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"approvedCredits":{"description":"The most the cover is charged, only when it is made.","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["projectId","job","approvedCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"6b1f0e2a-4c3d-4e5f-9a8b-7c6d5e4f3a2b","job":{"id":"job_019a1b2c3d4e5f6a7b8c9d0e","product":"stickman","kind":"stickman.thumbnail","resource":{"type":"project","id":"6b1f0e2a-4c3d-4e5f-9a8b-7c6d5e4f3a2b"},"status":"running","step":"Drawing the cover picture","progress":null,"result":null,"error":null,"createdAt":"2026-10-21T10:12:00.000Z","updatedAt":"2026-10-21T10:12:00.000Z","finishedAt":null,"poll_after_seconds":10},"approvedCredits":20}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"stickman_thumbnails_update_text","summary":"Change the words on a Stickman video's cover, on the picture already made. Answers with a job to follow.","description":"Lays new words on the cover picture already made (make it first with make_thumbnail; a picture you uploaded is used as it is and takes no words). A line you leave out stays as it is. Not charged; each change counts toward the daily finishing passes and the website's free cover changes a day. Answers 202 with a job.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.thumbnails.update_text","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_finish action=thumbnail_text","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"topLine":{"description":"The cover's short top line, up to 24 characters (a Story's is \"PART 2\"); \"\" leaves it off.","type":"string","maxLength":24},"title":{"description":"The cover's title in big letters, up to 48 characters.","type":"string","minLength":1,"maxLength":48}},"additionalProperties":false},"example":{"title":"SHE KEPT THE BAG"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The video (projectId from stickman_projects list or create).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The video (projectId from stickman_projects list or create).","example":"6b1f0e2a-4c3d-4e5f-9a8b-7c6d5e4f3a2b"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"job":{"description":"Follow it with autoclips_jobs get (or GET /v1/jobs/{id}). Its result has the new cover when it is done; a cover that is not made is not charged.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false}},"required":["projectId","job"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"6b1f0e2a-4c3d-4e5f-9a8b-7c6d5e4f3a2b","job":{"id":"job_019a1b2c3d4e5f6a7b8c9d0e","product":"stickman","kind":"stickman.thumbnail","resource":{"type":"project","id":"6b1f0e2a-4c3d-4e5f-9a8b-7c6d5e4f3a2b"},"status":"running","step":"Writing the words on the cover","progress":null,"result":null,"error":null,"createdAt":"2026-10-21T10:20:00.000Z","updatedAt":"2026-10-21T10:20:00.000Z","finishedAt":null,"poll_after_seconds":10}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/{projectId}/votes":{"get":{"operationId":"stickman_series_vote_status","summary":"See how counting the vote from your posts is going, and the count once it is ready.","description":"How counting a part's vote from the comments on its posts (TikTok, YouTube, Instagram, Facebook) is going: each post being read, then the count (each word's votes, the winner and its share) once state is ready. peek true only says which posts can be read, without reading anything. Ask again while state is importing (pollAfterSeconds). The comments themselves are never returned, only the counts.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.series.vote_status","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_series action=vote_status","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},{"name":"peek","in":"query","required":false,"schema":{"description":"True only lists the posts that can be read, without reading them.","type":"boolean"},"description":"True only lists the posts that can be read, without reading them."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"state":{"description":"ready (counted), importing (reading the comments: ask again), ready_to_count (count_votes starts it), no_posts or posting (nothing can be read yet), no_vote, failed, off.","type":"string","enum":["off","not_found","no_vote","no_posts","posting","ready_to_count","importing","failed","ready"]},"platforms":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"status":{"type":"string"},"comments":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"capped":{"description":"True when that post had more comments than are read.","type":"boolean"}},"required":["platform","status","comments","capped"],"additionalProperties":false}},"result":{"anyOf":[{"type":"object","properties":{"a":{"anyOf":[{"type":"string"},{"type":"null"}]},"b":{"anyOf":[{"type":"string"},{"type":"null"}]},"votesA":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"votesB":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"counted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ignored":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"tie":{"type":"boolean"},"winner":{"anyOf":[{"type":"string"},{"type":"null"}]},"loser":{"anyOf":[{"type":"string"},{"type":"null"}]},"percent":{"description":"The winner's share, 50 to 99 (null on a tie or with no votes): send it as vote.percent to next_part.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["a","b","votesA","votesB","counted","ignored","tie","winner","loser","percent"],"additionalProperties":false},{"type":"null"}]},"partial":{"description":"True when some posts are still being read and the count has the others only.","type":"boolean"},"cached":{"description":"True when the answer came from the last count (a part is read at most every few seconds).","type":"boolean"},"pollAfterSeconds":{"description":"Ask again after this many seconds while it is importing.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["state","platforms","result","partial","cached","pollAfterSeconds"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"state":"ready","platforms":[{"platform":"tiktok","status":"done","comments":43,"capped":false}],"result":{"a":"TRUST","b":"RUN","votesA":26,"votesB":15,"counted":41,"ignored":2,"tie":false,"winner":"TRUST","loser":"RUN","percent":63},"partial":false,"cached":false,"pollAfterSeconds":null}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"stickman_series_count_votes","summary":"Start counting the vote from the comments on the posts of a part.","description":"Starts reading the comments on the posts of a part (the ones it was posted as through AutoClips) and counts the vote; then ask vote_status until state is ready. A count is refreshed at most every two minutes; real reads are limited a day (429 daily_limit_reached) and a minute (429 rate_limited), shared with the app.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.series.count_votes","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_series action=count_votes","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"state":{"description":"ready (counted), importing (reading the comments: ask again), ready_to_count (count_votes starts it), no_posts or posting (nothing can be read yet), no_vote, failed, off.","type":"string","enum":["off","not_found","no_vote","no_posts","posting","ready_to_count","importing","failed","ready"]},"platforms":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"status":{"type":"string"},"comments":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"capped":{"description":"True when that post had more comments than are read.","type":"boolean"}},"required":["platform","status","comments","capped"],"additionalProperties":false}},"result":{"anyOf":[{"type":"object","properties":{"a":{"anyOf":[{"type":"string"},{"type":"null"}]},"b":{"anyOf":[{"type":"string"},{"type":"null"}]},"votesA":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"votesB":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"counted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ignored":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"tie":{"type":"boolean"},"winner":{"anyOf":[{"type":"string"},{"type":"null"}]},"loser":{"anyOf":[{"type":"string"},{"type":"null"}]},"percent":{"description":"The winner's share, 50 to 99 (null on a tie or with no votes): send it as vote.percent to next_part.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["a","b","votesA","votesB","counted","ignored","tie","winner","loser","percent"],"additionalProperties":false},{"type":"null"}]},"partial":{"description":"True when some posts are still being read and the count has the others only.","type":"boolean"},"cached":{"description":"True when the answer came from the last count (a part is read at most every few seconds).","type":"boolean"},"pollAfterSeconds":{"description":"Ask again after this many seconds while it is importing.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["state","platforms","result","partial","cached","pollAfterSeconds"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"state":"importing","platforms":[{"platform":"tiktok","status":"importing","comments":0,"capped":false}],"result":null,"partial":false,"cached":false,"pollAfterSeconds":4}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/projects/{projectId}/votes/pasted":{"post":{"operationId":"stickman_series_count_pasted_votes","summary":"Count the two vote words in comments you paste, one vote per line.","description":"Counts the part's two vote words in comments you paste (one comment per line, up to 5,000 lines): a line with one word is one vote however often it says it, a line with both is ignored, and a word counts only as a whole word in any case. The winner's share is 50 to 99; a tie names no winner. Nothing is stored or sent anywhere.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.series.count_pasted_votes","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_series action=count_pasted_votes","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"comments":{"description":"The comments, one per line (at most 200,000 characters).","type":"string","maxLength":200000}},"required":["comments"],"additionalProperties":false},"example":{"comments":"TRUST\nrun!!\ntrust trust\nTRUST or RUN?"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"A part of the series: the projectId of a Story video (from stickman_projects list or a series' parts).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"result":{"type":"object","properties":{"a":{"anyOf":[{"type":"string"},{"type":"null"}]},"b":{"anyOf":[{"type":"string"},{"type":"null"}]},"votesA":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"votesB":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"counted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ignored":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"tie":{"type":"boolean"},"winner":{"anyOf":[{"type":"string"},{"type":"null"}]},"loser":{"anyOf":[{"type":"string"},{"type":"null"}]},"percent":{"description":"The winner's share, 50 to 99 (null on a tie or with no votes): send it as vote.percent to next_part.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["a","b","votesA","votesB","counted","ignored","tie","winner","loser","percent"],"additionalProperties":false}},"required":["result"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"result":{"a":"TRUST","b":"RUN","votesA":2,"votesB":1,"counted":3,"ignored":1,"tie":false,"winner":"TRUST","loser":"RUN","percent":67}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/scripts/format":{"post":{"operationId":"stickman_scripts_format","summary":"Tidy a script written like a screenplay into the lines a narrator speaks, to check before planning.","description":"For a script with speaker names, scene headings or directions: it splits what is spoken from what is shown, and answers the blocks to check (each spoken line, with the places and actions before it). A plain script answers formatted:false and nothing else happens. The formatId goes to stickman_plans create with the script, once; what the tidy cost is part of that plan's planning, at cost. Paid plans only.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.scripts.format","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_story action=format_script","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"script":{"description":"Your script, up to 2,000 characters.","type":"string","minLength":1,"maxLength":4000}},"required":["script"],"additionalProperties":false},"example":{"script":"You open the fridge. A note says: do not eat the cake."}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"formatted":{"description":"false: a plain script, nothing to tidy.","type":"boolean"},"formatId":{"description":"Send it to stickman_plans create with the script (once).","type":"string"},"source":{"type":"string"},"review":{"type":"object","properties":{"blocks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"speaker":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"text":{"type":"string"},"before":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false}}},"required":["id","speaker","tags","text","before"],"additionalProperties":false}},"after":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false}}},"required":["blocks","after"],"additionalProperties":false}},"required":["formatted"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"formatted":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/scripts/measure":{"post":{"operationId":"stickman_scripts_measure","summary":"How long a pasted script reads, how many lines it makes, and what planning and the video would cost.","description":"Reads your own script the way a Story from it is made (My script): how many seconds it takes with this narrator, pace and language, the video length it fits, its lines, and the quote (planning at most, the video about and at most). A script that is too long or too short says by how much; a language that does not match the words asks you to confirm it (languageConfirmed). Nothing is saved and no model runs.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.scripts.measure","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_story action=measure_script","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"script":{"description":"Your script, as it should be spoken (up to 2,000 characters). Words in [square brackets] are sound cues.","type":"string","minLength":1,"maxLength":4000},"flavor":{"description":"Story kind: You Decide or True Story. A plan may also take auto: the planner picks from your idea. Story options (You Decide, True Story) need Stickman Story switched on for the account; stickman.capabilities.get says what is on right now.\nChoices:\n- you-decide — You Decide: You are the hero of a thriller. Every part ends on a vote, and the comments decide what happens in the next part.\n- true-story — True Story: A real rise or gamble, researched and told like a thriller.\nDefault: you-decide.","type":"string","enum":["you-decide","true-story"]},"language":{"title":"Language (Story) (Stickman videos (Explainer, Skit, Story) option storyLanguage)","description":"Language (Story): The language of a Story's narration, cards and captions. Some languages are switched on later than others: a language that is not offered yet is refused with language_not_offered, and stickman.capabilities.get lists what is offered now.\nChoices: one of 94 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=storyLanguage) to see them all.\nDefault: en.","type":"string"},"voiceId":{"description":"Narrator (Story): Who reads a Story. The last 14 (meta.v2Only) need the 20-voice switch; stickman.capabilities.get lists what is offered now. meta.sampleUrl plays a sample.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=storyVoice) to see them all.\nDefault: nPczCjzI2devNBz1zQrb. Or the voiceId of one of your own cloned voices (autoclips_voices, source \"cloned\").","type":"string","pattern":"^[A-Za-z0-9]{8,64}$"},"pace":{"description":"Reading pace: How fast the narrator reads. A faster pace fits more words into the same length.\nChoices:\n- relaxed — Relaxed: Everyday speaking pace — easiest to follow.\n- natural — Natural: Steady documentary read.\n- brisk — Brisk: Fast and punchy, still every word clear.\n- rapid — Rapid: Breathless, relentless — the hardest read to follow.\nDefault: brisk.","type":"string","enum":["relaxed","natural","brisk","rapid"]},"vote":{"description":"The end card's vote, for a You Decide script.","type":"object","properties":{"question":{"description":"The end card's question, 3 to 40 characters.","type":"string","minLength":3,"maxLength":40},"a":{"description":"The first choice, one short word.","type":"string","minLength":1,"maxLength":14},"b":{"description":"The second choice, one short word.","type":"string","minLength":1,"maxLength":14}},"required":["question","a","b"],"additionalProperties":false},"languageConfirmed":{"description":"Read it in the language you picked even though the words look like another.","type":"boolean"}},"required":["script"],"additionalProperties":false},"example":{"script":"You open the fridge. A note says: do not eat the cake. You look around. Nobody is home. You take one bite. The lights go out.","voiceId":"nPczCjzI2devNBz1zQrb"}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean"},"measure":{"type":"object","properties":{"seconds":{"type":"number"},"videoSeconds":{"type":"number"},"lines":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"label":{"type":"number"},"language":{"type":"string"},"voiceId":{"type":"string"},"pace":{"type":"string"},"vote":{"anyOf":[{"type":"object","properties":{"question":{"description":"The end card's question, 3 to 40 characters.","type":"string","minLength":3,"maxLength":40},"a":{"description":"The first choice, one short word.","type":"string","minLength":1,"maxLength":14},"b":{"description":"The second choice, one short word.","type":"string","minLength":1,"maxLength":14}},"required":["question","a","b"],"additionalProperties":false},{"type":"null"}]}},"required":["seconds","videoSeconds","lines","label","language","voiceId","pace","vote"],"additionalProperties":false},"quote":{"type":"object","properties":{"planning":{"type":"object","properties":{"atMost":{"type":"number"}},"required":["atMost"],"additionalProperties":false},"video":{"type":"object","properties":{"about":{"type":"number"},"atMost":{"type":"number"}},"required":["about","atMost"],"additionalProperties":false}},"required":["planning","video"],"additionalProperties":false},"problem":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"cut":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"}},"required":["unit","count"],"additionalProperties":false},"add":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"}},"required":["unit","count"],"additionalProperties":false},"detected":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","message"],"additionalProperties":false}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"ok":false,"problem":{"code":"script_too_short","message":"This script makes a 9-second video. A Story is at least 20 seconds: add about 30 words.","add":{"unit":"words","count":30},"detected":"en"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/series/{seriesId}":{"get":{"operationId":"stickman_series_get","summary":"Read a series: every part in order, how each one ends, and what can be made next.","description":"The series page: its name, its cast, every part in order (status, video, vote and its result, how it ends, the post text) and the next part that can be made. With chapters on, each part also says whether it is a chapter, the last part, how many parts the series was planned to have, and how the next part goes on from it.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.series.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_series action=get","parameters":[{"name":"seriesId","in":"path","required":true,"schema":{"description":"The series (series.seriesId of a part).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The series (series.seriesId of a part).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"series":{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"cast":{"type":"array","items":{"type":"object","properties":{"castId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"masterUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["castId","name","masterUrl"],"additionalProperties":false}},"parts":{"type":"array","items":{"type":"object","properties":{"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"vote":{"anyOf":[{"type":"object","properties":{"question":{"type":"string"},"a":{"type":"string"},"b":{"type":"string"}},"required":["a","b"],"additionalProperties":false},{"type":"null"}]},"voteResult":{"anyOf":[{"type":"object","properties":{"winner":{"type":"string"},"loser":{"anyOf":[{"type":"string"},{"type":"null"}]},"percent":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["winner","loser","percent"],"additionalProperties":false},{"type":"null"}]},"parentProjectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationS":{"anyOf":[{"type":"number"},{"type":"null"}]},"motion":{"anyOf":[{"type":"string"},{"type":"null"}]},"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"partLine":{"anyOf":[{"type":"string"},{"type":"null"}]},"ending":{"anyOf":[{"type":"string","enum":["vote","follow"]},{"type":"null"}]},"post":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["title","description"],"additionalProperties":false},{"type":"null"}]},"finalPart":{"description":"True for the series' last part.","type":"boolean"},"chapter":{"description":"True for a True Story part that went on with no vote.","type":"boolean"},"plannedParts":{"description":"How many parts the series was planned to have, when set.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"continues":{"description":"How the next part goes on from this one: by its vote, as the next chapter, or not at all.","anyOf":[{"type":"string","enum":["vote","chapter"]},{"type":"null"}]}},"required":["projectId","partNumber","title","status","videoUrl","vote","voteResult","parentProjectId","progress","thumbnailUrl","durationS","motion","question","partLine","ending","post","finalPart","chapter","plannedParts","continues"],"additionalProperties":false}},"storySoFar":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"next":{"anyOf":[{"type":"object","properties":{"fromProjectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"canMake":{"type":"boolean"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"plannedParts":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["fromProjectId","partNumber","canMake","reason","plannedParts"],"additionalProperties":false},{"type":"null"}]}},"required":["seriesId","title","cast","parts","next"],"additionalProperties":false}},"required":["series"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"series":{"seriesId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","title":"The Stranger","cast":[{"castId":"mara","name":"Mara","masterUrl":"https://media.autoclips.app/stickman/cast/mara.png"}],"parts":[{"projectId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","partNumber":1,"title":"The Stranger at the Door","status":"completed","videoUrl":"https://media.autoclips.app/stickman/part-1.mp4","vote":{"question":"Do you trust him?","a":"TRUST","b":"RUN"},"voteResult":null,"parentProjectId":null,"progress":100,"thumbnailUrl":null,"durationS":90,"motion":"classic","question":"Do you trust him?","partLine":"A stranger knocks at midnight.","ending":"vote","post":null,"finalPart":false,"chapter":false,"plannedParts":5,"continues":"vote"},{"projectId":"c4a2d3e5-6f70-4b8c-9dae-1f2a3b4c5d6e","partNumber":2,"title":"Inside the House","status":"completed","videoUrl":"https://media.autoclips.app/stickman/part-2.mp4","vote":{"question":"Do you trust him?","a":"TRUST","b":"RUN"},"voteResult":{"winner":"TRUST","loser":"RUN","percent":63},"parentProjectId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","progress":100,"thumbnailUrl":null,"durationS":90,"motion":"classic","question":"Do you trust him?","partLine":"You let him in.","ending":"vote","post":null,"finalPart":false,"chapter":false,"plannedParts":5,"continues":"vote"}],"next":{"fromProjectId":"c4a2d3e5-6f70-4b8c-9dae-1f2a3b4c5d6e","partNumber":3,"canMake":true,"reason":null,"plannedParts":5}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"stickman_series_rename","summary":"Rename a series on every one of its parts.","description":"Gives the series a new name (1 to 60 characters), shown on every one of its parts and on the series page. Needs series pages to be switched on.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.series.rename","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_series action=rename","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"The new series name, 1 to 60 characters.","type":"string","minLength":1,"maxLength":60}},"required":["title"],"additionalProperties":false},"example":{"title":"The Midnight Stranger"}}}},"parameters":[{"name":"seriesId","in":"path","required":true,"schema":{"description":"The series (series.seriesId of a part).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The series (series.seriesId of a part).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"seriesId":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["seriesId","title"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"seriesId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","title":"The Midnight Stranger"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/story/quick-start":{"post":{"operationId":"stickman_story_quick_start","summary":"Make a You Decide Story from an idea, with no planning step. What you approve is the video's spending limit.","description":"Starts a Stickman Story (You Decide) right away from your idea: the viewer is the hero, and it ends on a vote for the next part. There is no research or planning step and nothing is charged for planning. Your watermark and your outro (outroId, paid plans) can be added; they are put on when the video renders. What you approve is the video's spending limit: the most the run can be charged (its base, its moving scenes at their cap, a cover). Each step is charged as it is made, usually much less. It answers with a job at once (status 202); follow it with autoclips_jobs get. A True Story needs research: plan it with stickman_plans.\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. The limit is the most Stickman video can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"stickman.story.quick_start","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"stickman_story action=quick_start","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idea":{"description":"What happens to the viewer, 3 to 300 characters. Told in the second person (\"you\"), and it ends on a vote.","type":"string","minLength":3,"maxLength":300},"castCharacterIds":{"description":"Up to 5 cast members besides the viewer: My cast ids (stickman_cast list) or \"preset:<slug>\".","maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"lengthSeconds":{"description":"Story length: How long a Story (or a Story part) runs. It sets the base price; moving scenes are added on top.\nChoices:\n- 30 — 30 seconds: A 30-second story. (600 credits base (x your plan multiplier))\n- 40 — 40 seconds: A 40-second story. (750 credits base (x your plan multiplier))\n- 50 — 50 seconds: A 50-second story. (950 credits base (x your plan multiplier))\n- 60 — 1 minute: A 60-second story. (1100 credits base (x your plan multiplier))\n- 70 — 1.2 minutes: A 70-second story. (1250 credits base (x your plan multiplier))\n- 80 — 1.3 minutes: A 80-second story. (1400 credits base (x your plan multiplier))\n- 90 — 1.5 minutes: A 90-second story. (1550 credits base (x your plan multiplier))\n- 100 — 1.7 minutes: A 100-second story. (1700 credits base (x your plan multiplier))\n- 110 — 1.8 minutes: A 110-second story. (1850 credits base (x your plan multiplier))\n- 120 — 2 minutes: A 120-second story. (2000 credits base (x your plan multiplier))\nDefault: 90.","type":"string","enum":["30","40","50","60","70","80","90","100","110","120"]},"voiceId":{"description":"Narrator (Story): Who reads a Story. The last 14 (meta.v2Only) need the 20-voice switch; stickman.capabilities.get lists what is offered now. meta.sampleUrl plays a sample.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=storyVoice) to see them all.\nDefault: nPczCjzI2devNBz1zQrb. Or the voiceId of one of your own cloned voices (autoclips_voices, source \"cloned\").","type":"string","pattern":"^[A-Za-z0-9]{8,64}$"},"language":{"title":"Language (Story) (Stickman videos (Explainer, Skit, Story) option storyLanguage)","description":"Language (Story): The language of a Story's narration, cards and captions. Some languages are switched on later than others: a language that is not offered yet is refused with language_not_offered, and stickman.capabilities.get lists what is offered now.\nChoices: one of 94 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=storyLanguage) to see them all.\nDefault: en.","type":"string"},"captions":{"description":"Show captions (default on).","type":"boolean"},"captionStyle":{"description":"The caption look. Leave a key out to keep the format's own.","type":"object","properties":{"highlightStyle":{"description":"Caption look: How the spoken words appear on screen (captionStyle.highlightStyle). The same looks every AutoClips format uses.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionStyle) to see them all.\nDefault: The format's own look (leave it out).","type":"string","enum":["classic","color-only","scale-up","typewriter","progressive","karaoke","bounce","outline","background","shadow-pop","pop-color","neon","underline","gradient","boxed","glow"]},"fontFamily":{"description":"Caption font: The lettering of the captions (captionStyle.fontFamily).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionFont) to see them all.\nDefault: The caption look's own font (leave it out).","type":"string","enum":["Montserrat","BebasNeue","Anton","LeagueSpartan"]},"position":{"description":"Caption position: Where the captions sit (captionStyle.position).\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=captionPosition) to see them all.\nDefault: The format's own position (leave it out).","type":"string","enum":["top","upper-third","center","lower-third","bottom"]},"positionY":{"description":"Where the captions sit, 0 (top) to 100 (bottom); wins over position.","type":"number","minimum":0,"maximum":100},"groupSize":{"description":"Words at a time: How many words the captions show at once (captionStyle.groupSize, sent as a number).\nChoices:\n- 2 — 2 words: Punchy. Reads fastest.\n- 3 — 3 words: The default.\n- 4 — 4 words: Calmer, fewer changes.\nDefault: The caption look's own size (leave it out).","type":"string","enum":["2","3","4"]},"fontSize":{"description":"Caption size, 28 to 110.","type":"integer","minimum":28,"maximum":110},"color":{"description":"Caption colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"highlightColor":{"description":"The spoken word's colour, #RRGGBB.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"showBackground":{"description":"A box behind the captions.","type":"boolean"},"backgroundOpacity":{"description":"How solid that box is, 0 to 1.","type":"number","minimum":0,"maximum":1}},"additionalProperties":false},"cards":{"description":"The Story's text cards. Leave it out for the default.","type":"object","properties":{"enabled":{"description":"Draw the on-screen text cards (needs the cards switch: stickman.capabilities.get).","type":"boolean"},"theme":{"description":"Text card look: The look of a Story's on-screen text cards and its end card.\nChoices:\n- night — Night: Dark card, green edge.\n- ink — Ink: Dark tiles, pink accents, paper fact cards.\n- clean — Clean: White card, black text.\nDefault: Night for You Decide, Ink for True Story (leave it out).","type":"string","enum":["night","ink","clean"]}},"additionalProperties":false},"motion":{"description":"Story motion: How much of a Story moves. Moving scenes are paid plans only and are charged as each one is made, never above the quote's \"at most\". Story options (You Decide, True Story) need Stickman Story switched on for the account; stickman.capabilities.get says what is on right now.\nChoices:\n- stills — Stills: Pictures with camera moves; nothing is animated.\n- key — Key moments: The key moments of the story move. (118 credits a moving scene (a 5-second clip on AutoClips 1; storyMotionModel changes it), at most the quote's cap; plans: paid)\n- full — Full motion: Every picture scene moves. (118 credits a moving scene (a 5-second clip on AutoClips 1; storyMotionModel changes it), at most the quote's cap; plans: paid)\nDefault: stills.","type":"string","enum":["stills","key","full"]},"bestClip":{"description":"Best Clip: up to 3 takes of each moving scene, the best one kept. Every take is charged. Only with key or full motion.","type":"boolean"},"motionModel":{"description":"Story clip model: Story motion only: the AutoClips model the moving scenes are filmed with. Characters who speak (Character Speaks) are filmed on AutoClips 1 when a Lite model is picked. A next part keeps its part before's model unless you name one. Story options (You Decide, True Story) need Stickman Story switched on for the account; stickman.capabilities.get says what is on right now.\nChoices:\n- autoclips1 — AutoClips 1: Our main model, 768p. Each clip runs as long as its scene. (118 credits a moving scene (a 5-second clip); plans: paid)\n- autoclips1Upscaled — AutoClips 1 1080p Upscaled: AutoClips 1, sharpened to 1080p. (157 credits a moving scene (a 5-second clip); plans: paid)\n- autoclips1Light — AutoClips 1 Lite: Half the price, 720p. (63 credits a moving scene (a 5-second clip); talking clips are priced as AutoClips 1; plans: paid)\n- autoclips1LightHd — AutoClips 1 Lite Full HD: AutoClips 1 Lite drawn at full 1080p. (173 credits a moving scene (a 5-second clip); talking clips are priced as AutoClips 1; plans: paid)\nDefault: autoclips1.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd"]},"videoSpeed":{"description":"Video speed: How fast the finished video plays, from 1x to 3x in steps of 0.1. The page's quick picks: 1x, 1.1x, 1.2x, 1.3x, 1.5x, 2x, 3x. Free: it changes no price. From 1 to 3 x, in steps of 0.1. Default: 1.","type":"number","minimum":1,"maximum":3,"multipleOf":0.1},"musicTrackId":{"title":"Music (Stickman videos (Explainer, Skit, Story) option musicTrack)","description":"Music: A music track by id: \"none\" (no music, when an Explainer or Skit is made; a render refuses it, since a render always keeps the video's music: turn a Story's music off with the edit music.none), a track of the music library, or a Story music bed (meta.kind \"bed\"). Links are never taken: the id picks the track.\nChoices: one of 232 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=musicTrack) to see them all.\nDefault: The format's default (Story: the series bed) (leave it out).","type":"string"},"artStyle":{"description":"Art style: The look of the pictures in a Story: the places, the light and the colours. The stick figures stay the same in every style. A next part keeps the style of the part before it. meta.exampleUrl shows the same scene in each style.\nChoices:\n- default — Cinematic: Painted night scenes in teal and warm orange. The classic look. Best for any story.\n- horror — Horror Glow: Dark and creepy, lit by vivid green, red and purple light. Best for scary, survival and mystery stories.\n- noir — Rainy Noir: Rain-soaked streets, hard shadows and cold blue light. Crime and secrets. Best for crime, heists and true stories.\n- sunny — Bright Day: Sunny, colourful and cheerful, like a Saturday-morning cartoon. Best for funny, feel-good and kids stories.\n- epic — Golden Epic: Huge skies, golden sunsets and dust in the air. Feels like a movie. Best for history, war and adventure.\nDefault: default.","type":"string","enum":["default","horror","noir","sunny","epic"]},"watermarkType":{"description":"Watermark: Your text or picture on the video. Every plan.\nChoices:\n- none — None: No watermark.\n- text — Text: watermarkText.\n- image — Picture: watermarkMediaId.\nDefault: none.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"Text: The words. Default: No text (leave it out).","type":"string","minLength":1,"maxLength":50},"watermarkTextColor":{"description":"Text colour: #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundColor":{"description":"Box colour: #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundOpacity":{"description":"Box: Box, 0 (none) to 1. From 0 to 1, in steps of 0.01. Default: 0.5.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"watermarkMediaId":{"description":"A picture from autoclips_media, by id. Default: No picture (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"watermarkImageOpacity":{"description":"Picture opacity: 0.3 to 1. From 0.3 to 1, in steps of 0.01. Default: 0.7.","type":"number","minimum":0.3,"maximum":1,"multipleOf":0.01},"watermarkVerticalPosition":{"description":"Height: Percent from the top. From 10 to 90 percent. Default: 85.","type":"integer","minimum":10,"maximum":90},"watermarkHorizontalPosition":{"description":"Across: Percent from the left. From 5 to 95 percent. Default: 85.","type":"integer","minimum":5,"maximum":95},"watermarkScale":{"description":"Size: 1 is normal. From 0.5 to 3, in steps of 0.01. Default: 1.","type":"number","minimum":0.5,"maximum":3,"multipleOf":0.01},"watermarkStartSeconds":{"description":"From: Seconds into the video it appears. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"watermarkEndSeconds":{"description":"Until: Seconds into the video it goes; 0 = to the end. At least 0.5 s after the start. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"outroId":{"description":"Outro: An end card from autoclips_outros, after the last scene. Paid plans (free: plan_required). \"none\" = no outro. A Story's own end card still closes the story; the outro plays after it. Default: No outro (leave it out).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["idea"],"additionalProperties":false},"example":{"idea":"You find a bag of money in a stranger's car","lengthSeconds":"90"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"description":"The video id (projectId).","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"type":"string","enum":["explainer","skit","story"]},"storyFlavor":{"description":"you-decide or true-story for a Story.","anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"description":"Where it is, in one word.","type":"string","enum":["queued","writing","voicing","drawing","filming","transcribing","preview_ready","rendering","completed","failed"]},"status":{"description":"The raw status word.","type":"string"},"progress":{"description":"Percent done, 0 to 100.","type":"number"},"video":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","status"],"additionalProperties":false},"thumbnail":{"anyOf":[{"type":"object","properties":{"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","url"],"additionalProperties":false},{"type":"null"}]},"series":{"anyOf":[{"type":"object","properties":{"seriesId":{"anyOf":[{"type":"string"},{"type":"null"}]},"partNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"parentProjectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextPartNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextPartProjectId":{"type":"string"}},"required":["seriesId","partNumber","parentProjectId"],"additionalProperties":false},{"type":"null"}]},"automation":{"anyOf":[{"type":"object","properties":{"automationId":{"type":"string"}},"required":["automationId"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"description":"Open it in the app.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","kind","storyFlavor","title","topic","stage","status","progress","video","thumbnail","series","automation","createdAt","updatedAt","appUrl"],"additionalProperties":false},"job":{"description":"Follow it with autoclips_jobs get. It succeeds with result.videoUrl when the video is ready.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"approvedCredits":{"description":"The spending limit you approved. Nothing is charged yet: each step is charged as it is made, usually much less.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["project","job","approvedCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"3f2c9a10-5b7e-4c1d-9e0f-1a2b3c4d5e6f","kind":"story","storyFlavor":"you-decide","title":"You find a bag of money in a stranger's car","topic":"You find a bag of money in a stranger's car","stage":"queued","status":"queued","progress":3,"video":{"url":null,"status":null},"thumbnail":null,"series":{"seriesId":"3f2c9a10-5b7e-4c1d-9e0f-1a2b3c4d5e6f","partNumber":1,"parentProjectId":null},"automation":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","appUrl":"https://app.autoclips.app/stickman?sessionId=3f2c9a10-5b7e-4c1d-9e0f-1a2b3c4d5e6f"},"job":{"id":"job_66f2a0000000000000000a01","product":"stickman","kind":"stickman.video","resource":{"type":"project","id":"3f2c9a10-5b7e-4c1d-9e0f-1a2b3c4d5e6f"},"status":"running","step":"Waiting to start","progress":3,"result":null,"error":null,"createdAt":"2026-10-25T10:00:00.000Z","updatedAt":"2026-10-25T10:00:00.000Z","finishedAt":null,"poll_after_seconds":15},"approvedCredits":1570}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/uploads":{"post":{"operationId":"stickman_uploads_create","summary":"Add a picture from your media library for Stickman Story plans, My cast or the editor.","description":"Takes a picture you already have in your media library (upload it with autoclips_media first) and adds it to Stickman Story: it is turned upright, its metadata (location included) is removed, and its long edge is kept to 2,048 pixels. JPG, PNG or WebP, at most 8 MB. The same media picture added twice gives back the first upload. Use the upload id in stickman_plans create (pictures), stickman_cast create, or a plan's cast look.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"stickman.uploads.create","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_story action=upload_image","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mediaId":{"description":"A picture from your media library (autoclips_media).","type":"string","pattern":"^[a-f0-9]{24}$"},"name":{"description":"A file name to keep with it (default: the library's).","type":"string","minLength":1,"maxLength":120}},"required":["mediaId"],"additionalProperties":false},"example":{"mediaId":"66f2a0000000000000000b01"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"upload":{"type":"object","properties":{"id":{"description":"The uploadId: use it in stickman_plans create pictures, stickman_cast create, or a plan's cast look.","type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"width":{"anyOf":[{"type":"number"},{"type":"null"}]},"height":{"anyOf":[{"type":"number"},{"type":"null"}]},"hasAlpha":{"type":"boolean"}},"required":["id","url","width","height","hasAlpha"],"additionalProperties":false}},"required":["upload"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"upload":{"id":"0b8f1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d","url":"https://media.autoclips.app/v3-images/stickman/uploads/u/0b8f1c2d.jpg","width":1536,"height":2048,"hasAlpha":false}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stickman/voices/{voiceId}/sample":{"get":{"operationId":"stickman_voices_sample","summary":"Hear a Story narrator in one language: a link to a short sample.","description":"A short sample of a Story narrator speaking a language. Most samples are ready at once; one never played before is made on first play and answers ready:false for a moment: ask again a few seconds later.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Stickman videos (Explainer, Skit, Story)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"stickman.voices.sample","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"stickman_story action=voice_sample","parameters":[{"name":"voiceId","in":"path","required":true,"schema":{"description":"Narrator (Story): Who reads a Story. The last 14 (meta.v2Only) need the 20-voice switch; stickman.capabilities.get lists what is offered now. meta.sampleUrl plays a sample.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=storyVoice) to see them all.\nDefault: nPczCjzI2devNBz1zQrb.","type":"string","enum":["nPczCjzI2devNBz1zQrb","JBFqnCBsd6RMkjVDRZzb","EXAVITQu4vr4xnSDxMaL","pNInz6obpgDQGcFmaJgB","TxGEqnHWrfWFTfGW9XjX","onwK4e9ZLuTAKqWW03F9","N2lVS1w4EtoT3dr4eOWO","cjVigY5qzO86Huf0OWal","pqHfZKP75CvOlQylNhV4","iP95p4xoKVk53GoZ742B","TX3LPaxmHKxFdv7VOQHJ","IKne3meq5aSn9XLyUdCD","CwhRBWXzGAHq8TQ4Fs17","pFZP5JQG7iQjIQuC4Bku","Xb7hH8MSUJpSbSDYk0k2","9BWtsMINqrJLrRacOk9x","XrExE9yKIg1WjnnlVkGX","cgSgspJ2msm6clMCkdW9","FGY2WhTYpPnrIDTdsKH5","XB0fDUnXU5powFXDhCwa"]},"description":"Narrator (Story): Who reads a Story. The last 14 (meta.v2Only) need the 20-voice switch; stickman.capabilities.get lists what is offered now. meta.sampleUrl plays a sample.\nChoices: call autoclips_options (GET /api/v1/options?product=stickman&option=storyVoice) to see them all.\nDefault: nPczCjzI2devNBz1zQrb.","example":"nPczCjzI2devNBz1zQrb"},{"name":"language","in":"query","required":false,"schema":{"default":"en","title":"Language (Story) (Stickman videos (Explainer, Skit, Story) option storyLanguage)","description":"Language (Story): The language of a Story's narration, cards and captions. Some languages are switched on later than others: a language that is not offered yet is refused with language_not_offered, and stickman.capabilities.get lists what is offered now.\nChoices: one of 94 ids: call autoclips_options (GET /api/v1/options?product=stickman&option=storyLanguage) to see them all.\nDefault: en.","type":"string"},"example":"en"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"voiceId":{"type":"string"},"language":{"type":"string"},"ready":{"type":"boolean"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"type":"string"}},"required":["voiceId","language","ready","url"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"voiceId":"nPczCjzI2devNBz1zQrb","language":"en","ready":true,"url":"https://app.autoclips.app/stickman/voices/nPczCjzI2devNBz1zQrb-v2.mp3"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/ideas/brainstorm":{"post":{"operationId":"studio_ideas_brainstorm","summary":"Talk film ideas through with a Studio writer. Billed at the AI's actual cost (a few credits); asks first.","description":"One turn of Studio's brainstorm chat: the writer helps find topics, hooks, characters and story turns for short 3D animated films, and answers anything else too. Nothing is saved: send the earlier turns as history (up to 16). writerModel picks the writer (default: Claude Opus 5.5 on a paid plan, Kimi K3 on the free plan, as a new project in the app starts); webSearch lets it read the web for current facts. Billed at the AI's actual cost after the answer, usually a few credits; the price you approve is the most it can cost. The answer comes back directly when it is quick; otherwise the call answers 202 with a job, and the answer arrives in the job's result. A job's result has a size limit: an answer longer than it holds comes with answerCut true and only its start there, and read_result (with the job id) gives the whole answer, every word you paid for. billing: settled (charged at the actual cost, at most the approved price), pending (the cost was not reported yet; it is worked out later, and the approved price counts toward your key's daily credit cap meanwhile) or review (the bill came in above the approved price and giving back the difference failed; support returns it).\n\n**Permissions:** spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["spend"]}],"x-autoclips-operation":"studio.ideas.brainstorm","x-autoclips-scopes":["spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"studio_ideas action=brainstorm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"description":"What you want to talk through, in your own words.","type":"string","minLength":1,"maxLength":24000},"history":{"description":"The earlier turns of this chat, oldest first (up to 16; very long ones are dropped from the oldest).","maxItems":16,"type":"array","items":{"type":"object","properties":{"role":{"description":"Who said it: user (you) or assistant (an earlier answer).","type":"string","enum":["user","assistant"]},"content":{"description":"What was said.","type":"string","minLength":1,"maxLength":24000}},"required":["role","content"],"additionalProperties":false}},"writerModel":{"description":"Writer: Which AI writes the brief and the script. Billed at the real AI cost after each request. Every writer is offered on every plan; a new project starts on the app's pick for your plan.\nChoices:\n- opus55 — Claude Opus 5.5: Strongest physical logic and continuity for demanding stories. A 30-second script costs about 210 credits, a longer one more (billed at the real AI cost).\n- trendScout — Kimi K3: Strong, timely, research-led story development. A 30-second script costs about 158 credits, a longer one more (billed at the real AI cost).\n- quickSpark — Gemini 3.8 Flash: Fast brainstorming with clear visual beats. A 30-second script costs about 36 credits, a longer one more (billed at the real AI cost).\nDefault: Claude Opus 5.5 on a paid plan, Kimi K3 on the free plan (leave it out).","type":"string","enum":["opus55","trendScout","quickSpark"]},"webSearch":{"description":"Let the writer read the web for current facts. Adds a little to the price. Default false.","type":"boolean"},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"required":["prompt"],"additionalProperties":false},"example":{"prompt":"Give me three funny ideas for a 30-second film about a cat who runs a bakery."}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"description":"done: the answer is here. running: it is still being written; follow job with autoclips_jobs get, the answer comes in the job's result (read_result gives it whole).","type":"string","enum":["done","running"]},"jobId":{"description":"The job of this request (autoclips_jobs get).","type":"string"},"job":{"description":"The job, while the answer is still being written.","anyOf":[{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},{"type":"null"}]},"answer":{"description":"The writer's answer (Markdown), once done.","anyOf":[{"type":"string"},{"type":"null"}]},"truncated":{"description":"True when the answer hit its length limit and ends early.","type":"boolean"},"writer":{"anyOf":[{"type":"string"},{"type":"null"}]},"researched":{"type":"boolean"},"creditsCharged":{"description":"What this answer actually cost, once done.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"billing":{"type":"string","enum":["settled","pending","review"]}},"required":["status","jobId","job","answer"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/ideas/results/{jobId}":{"get":{"operationId":"studio_ideas_result","summary":"The whole answer of a brainstorm, or every trend idea uncut, from its job. Free.","description":"A brainstorm or trend research that answered with a job keeps its whole result: the full answer, every word however long, or every idea uncut, even when the job's own result had to shorten it (answerCut or ideasTrimmed true there). Send the job id (jobId in the answer of brainstorm or trending, or from autoclips_jobs). While it is still being written, status is running; if it did not finish, status is failed with the reason in message. Answers are kept for 30 days. Free.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"studio.ideas.result","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_ideas action=read_result","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"description":"The job of a brainstorm or trend research (jobId in its answer).","type":"string","pattern":"^job_[0-9a-f]{24}$"},"description":"The job of a brainstorm or trend research (jobId in its answer).","example":"job_0192f3a4b5c6d7e8f9a0b1c2"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"jobId":{"type":"string"},"kind":{"description":"Which request this job was.","type":"string","enum":["brainstorm","trending"]},"status":{"description":"succeeded: the whole result is here. running: still being written; ask again in a few seconds. failed: it did not finish (message says why).","type":"string","enum":["running","succeeded","failed"]},"message":{"description":"Why it failed, or what to do while it runs.","anyOf":[{"type":"string"},{"type":"null"}]},"answer":{"description":"A brainstorm's whole answer (Markdown).","anyOf":[{"type":"string"},{"type":"null"}]},"truncated":{"description":"True when the writer hit its own length limit and the answer ends early.","anyOf":[{"type":"boolean"},{"type":"null"}]},"writer":{"anyOf":[{"type":"string"},{"type":"null"}]},"researched":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"ideas":{"description":"Every trend idea, uncut, strongest first.","anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rank":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"title":{"type":"string"},"category":{"type":"string"},"trendSignal":{"description":"Why it counts as trending, in a few words.","type":"string"},"score":{"description":"How strong a film it would make, 0-100.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"angle":{"description":"The short-film story angle.","type":"string"},"whyNow":{"type":"string"},"hook":{"description":"A factual opening line.","type":"string"},"prompt":{"description":"A ready-to-use film idea: use it as the idea of a new project (studio_projects create).","type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"}},"required":["title","url"],"additionalProperties":false}}},"required":["id","rank","title","category","trendSignal","score","angle","whyNow","hook","prompt","sources"],"additionalProperties":false}},{"type":"null"}]},"refreshedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsCharged":{"description":"What it cost.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"billing":{"anyOf":[{"type":"string","enum":["settled","pending","review"]},{"type":"null"}]}},"required":["jobId","kind","status","message","answer","truncated","writer","researched","category","ideas","refreshedAt","creditsCharged","billing"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/ideas/trending":{"post":{"operationId":"studio_ideas_trending","summary":"Research what is trending right now and get ten film ideas with sources. Billed at the AI's actual cost; asks first.","description":"A Studio writer (Kimi K3) searches the web deeply for stories moving in the last few days in one topic (category, default \"all\"), optionally through your niche, and answers with ten ranked film ideas, each with why it is trending now, a hook, a ready-to-use film idea and its sources. Billed at the AI's actual cost after the answer, usually a few dozen credits; the price you approve is the most it can cost. It usually takes a minute or two, so it answers 202 with a job, and the ideas arrive in the job's result (it answers directly when it is quick). A job's result has a size limit: ideas too long for it come with ideasTrimmed true and their texts shortened there (every idea is kept), and read_result (with the job id) gives them uncut. Nothing is saved on a project. billing: settled (charged at the actual cost, at most the approved price), pending (the cost was not reported yet; it is worked out later, and the approved price counts toward your key's daily credit cap meanwhile) or review (the bill came in above the approved price and giving back the difference failed; support returns it).\n\n**Permissions:** spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["spend"]}],"x-autoclips-operation":"studio.ideas.trending","x-autoclips-scopes":["spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"studio_ideas action=trending","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"description":"Trend topic: For \"find me a trending story\": which kind of news to look through.\nChoices:\n- all — All trends: Trends in the strongest stories across every category, with at least six different categories represented.\n- technology — Technology: Trends in consumer technology, major product launches, cybersecurity, startups, gadgets, and the future of computing.\n- ai — AI: Trends in artificial intelligence breakthroughs, products, research, creative tools, robots, and industry shifts.\n- drama — Drama: Trends in major public disputes, internet controversies, surprising reversals, and high-interest developing stories.\n- hollywood — Hollywood: Trends in movies, television, casting, trailers, box office, awards, studios, and streaming releases.\n- celebrity — Celebrity: Trends in widely discussed public figures, interviews, career moments, relationships, and verified celebrity news.\n- entertainment — Entertainment: Trends in music, games, creators, streaming, live events, fandoms, and broader pop culture.\n- education — Education: Trends in fascinating explainers, discoveries, learning trends, student life, careers, and ideas people want clarified.\n- politics — Politics: Trends in major policy, elections, government decisions, diplomacy, and verified public-interest political developments.\n- sports — Sports: Trends in major games, athletes, records, transfers, rivalries, tournaments, and surprising sports moments.\nDefault: all.","type":"string","enum":["all","technology","ai","drama","hollywood","celebrity","entertainment","education","politics","sports"]},"niche":{"description":"Your audience or niche, as a second lens (for example \"home bakers\" or \"indie game fans\"). It never overrides the topic.","type":"string","minLength":1,"maxLength":180},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{"category":"ai"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"description":"done: the answer is here. running: it is still being written; follow job with autoclips_jobs get, the answer comes in the job's result (read_result gives it whole).","type":"string","enum":["done","running"]},"jobId":{"description":"The job of this request (autoclips_jobs get).","type":"string"},"job":{"description":"The job, while the answer is still being written.","anyOf":[{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"ideas":{"description":"Ten ideas, strongest first, once done.","anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rank":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"title":{"type":"string"},"category":{"type":"string"},"trendSignal":{"description":"Why it counts as trending, in a few words.","type":"string"},"score":{"description":"How strong a film it would make, 0-100.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"angle":{"description":"The short-film story angle.","type":"string"},"whyNow":{"type":"string"},"hook":{"description":"A factual opening line.","type":"string"},"prompt":{"description":"A ready-to-use film idea: use it as the idea of a new project (studio_projects create).","type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"}},"required":["title","url"],"additionalProperties":false}}},"required":["id","rank","title","category","trendSignal","score","angle","whyNow","hook","prompt","sources"],"additionalProperties":false}},{"type":"null"}]},"refreshedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsCharged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"billing":{"type":"string","enum":["settled","pending","review"]}},"required":["status","jobId","job","ideas"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects":{"get":{"operationId":"studio_projects_list","summary":"Your 3D Animated Studio projects, newest first. Search by words in the title or idea.","description":"Lists your Studio 2.0 projects, most recently changed first, with their status, settings and finished film. search finds words in the title or the idea (not case sensitive). Page with limit and next_cursor. A search looks through up to 500 projects per page, so a page can hold fewer than limit items while has_more is true.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"studio.projects.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_projects action=list","parameters":[{"name":"limit","in":"query","required":false,"schema":{"description":"How many items to return (1–100, default 20).","type":"integer","minimum":1,"maximum":100},"description":"How many items to return (1–100, default 20).","example":10},{"name":"cursor","in":"query","required":false,"schema":{"description":"The next_cursor from the previous page.","type":"string","maxLength":512},"description":"The next_cursor from the previous page."},{"name":"search","in":"query","required":false,"schema":{"description":"Only projects whose title or idea contains these words (not case sensitive).","type":"string","minLength":1,"maxLength":80},"description":"Only projects whose title or idea contains these words (not case sensitive).","example":"robot"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"studio"},"title":{"description":"The film's name: the script's title once there is one, unless the project was given a name of its own. Until it is renamed, the app's history list may still show the first words of the idea.","type":"string"},"status":{"description":"How far the film got: new (Just an idea so far); brainstorming (Idea saved, no script yet); research_ready (Trend ideas found, no script yet); script_ready (Script written); film_ready (Film ready). film_ready while the project holds a finished video (video); stage says where the film is in more detail.","type":"string"},"stage":{"description":"Where the film is, in plain words: an open Autopilot run and its step, else \"Film ready\" with its length, else how many clips are made, else the status.","type":"string"},"mode":{"description":"director = made step by step; autopilot = Autopilot makes the whole film.","type":"string","enum":["director","autopilot"]},"step":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"settings":{"description":"The settings, in the same words create and update take.","type":"object","properties":{},"additionalProperties":{}},"idea":{"anyOf":[{"type":"string"},{"type":"null"}]},"counts":{"type":"object","properties":{},"additionalProperties":{}},"video":{"description":"The finished film, once there is one.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"autopilot":{"description":"The Autopilot run, when one was started.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"openInApp":{"description":"True while an app tab is editing the project (it saved in the last 90 seconds). The API cannot change it until that tab has been still for 90 seconds or is closed.","type":"boolean"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"app":{"type":"string"},"editor":{"type":"string"}},"required":["app","editor"],"additionalProperties":{}}},"required":["id","product","title","status","stage","mode","step","durationSeconds","settings","idea","counts","video","autopilot","openInApp","createdAt","updatedAt","links"],"additionalProperties":{}}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"has_more":{"type":"boolean"}},"required":["items","next_cursor","has_more"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"items":[{"id":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19","product":"studio","title":"A tiny robot tries to return a lost star to the sky","status":"brainstorming","stage":"Idea saved, no script yet","mode":"director","step":"script-analysis","durationSeconds":30,"settings":{"writerModel":"trendScout","webSearch":false,"aspectRatio":"9:16","quality":"1080p","nativeAudio":true,"imageModel":"dream5","inSceneText":true,"textOnTop":true,"whoSpeaks":"auto","musicSource":"studio","productionModel":"trendScout","enhanceBrief":true,"speed":1.1},"idea":"A tiny robot tries to return a lost star to the sky","counts":{"scenes":0,"characters":0,"assets":0,"clips":0,"clipsReady":0,"finalVideos":0},"video":null,"autopilot":null,"openInApp":false,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","links":{"app":"https://app.autoclips.app/studio-2?projectId=9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19","editor":"https://app.autoclips.app/editor/9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"}}],"next_cursor":null,"has_more":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"studio_projects_create","summary":"Start a Studio project from an idea, with its settings and up to 16 pictures. Free.","description":"Creates a Studio 2.0 project from your idea, exactly as typing the idea into the app would: nothing is written or charged yet. Then start Autopilot with studio_autopilot to make the whole film (it costs credits and asks first), or open links.app to direct it step by step. These choices are used when Autopilot makes the film (studio_autopilot start uses them unless you send others), and the app shows them in its Autopilot panel. The one exception is enhanceBrief (improve my idea first): Autopilot never reads it, so studio_autopilot start writes from your idea as you typed it (or from an improved version the app already made); it only counts when the script is started in the app. If you direct the film step by step in the app instead, you pick the frame, quality, voices and sound, and picture maker again in its later steps. Every new Studio film lets the writer decide, scene by scene, whether a narrator or the characters speak. attachments are pictures from your media library (up to 16, each up to 10 MB, PNG, JPG, WebP or GIF) that the writer looks at; the writer you pick takes at most 16 (Claude Opus 5.5), 8 (Kimi K3) or 16 (Gemini 3.8 Flash). They are copied into Studio.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.projects.create","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_projects action=create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idea":{"description":"What the film is about, in your own words (3 to 12,000 characters). A sentence is enough; the writer builds the story.","type":"string","minLength":3,"maxLength":12000},"writerModel":{"description":"Writer: Which AI writes the brief and the script. Billed at the real AI cost after each request. Every writer is offered on every plan; a new project starts on the app's pick for your plan.\nChoices:\n- opus55 — Claude Opus 5.5: Strongest physical logic and continuity for demanding stories. A 30-second script costs about 210 credits, a longer one more (billed at the real AI cost).\n- trendScout — Kimi K3: Strong, timely, research-led story development. A 30-second script costs about 158 credits, a longer one more (billed at the real AI cost).\n- quickSpark — Gemini 3.8 Flash: Fast brainstorming with clear visual beats. A 30-second script costs about 36 credits, a longer one more (billed at the real AI cost).\nDefault: Claude Opus 5.5 on a paid plan, Kimi K3 on the free plan (leave it out).","type":"string","enum":["opus55","trendScout","quickSpark"]},"productionModel":{"description":"Planning AI: Which AI plans the pictures, character sheets and clips from the script (it looks at the pictures, so only vision-capable writers). A new project starts on the app's pick for your plan.\nChoices:\n- opus55 — Claude Opus 5.5: Strongest physical logic and continuity for demanding stories. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 783 credits, a longer film or a bigger cast more (billed at the real AI cost).\n- trendScout — Kimi K3: Strong, timely, research-led story development. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 589 credits, a longer film or a bigger cast more (billed at the real AI cost).\n- quickSpark — Gemini 3.8 Flash: Fast brainstorming with clear visual beats. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 150 credits, a longer film or a bigger cast more (billed at the real AI cost).\nDefault: Claude Opus 5.5 on a paid plan, Kimi K3 on the free plan (leave it out).","type":"string","enum":["opus55","trendScout","quickSpark"]},"durationSeconds":{"description":"Length: How many seconds of story are written and rendered as clips. The finished film lasts that divided by its speed: a new film plays at 1.1x, so 30 seconds of clips make a film of about 27 seconds; pick speed 1 for the full length. Clips are the main cost, and they scale with length (the speed does not change the price).\nChoices:\n- 20 — 20 seconds: 20 seconds of clips: a film of about 18 seconds at the 1.1x speed a new film plays at, 20 seconds at 1x.\n- 30 — 30 seconds: 30 seconds of clips: a film of about 27 seconds at the 1.1x speed a new film plays at, 30 seconds at 1x.\n- 40 — 40 seconds: 40 seconds of clips: a film of about 36 seconds at the 1.1x speed a new film plays at, 40 seconds at 1x.\n- 50 — 50 seconds: 50 seconds of clips: a film of about 45 seconds at the 1.1x speed a new film plays at, 50 seconds at 1x.\n- 60 — 60 seconds: 60 seconds of clips: a film of about 55 seconds at the 1.1x speed a new film plays at, 60 seconds at 1x.\n- 70 — 70 seconds: 70 seconds of clips: a film of about 64 seconds at the 1.1x speed a new film plays at, 70 seconds at 1x.\n- 80 — 80 seconds: 80 seconds of clips: a film of about 73 seconds at the 1.1x speed a new film plays at, 80 seconds at 1x.\n- 90 — 90 seconds: 90 seconds of clips: a film of about 82 seconds at the 1.1x speed a new film plays at, 90 seconds at 1x.\nDefault: 30.","anyOf":[{"description":"Length: How many seconds of story are written and rendered as clips. The finished film lasts that divided by its speed: a new film plays at 1.1x, so 30 seconds of clips make a film of about 27 seconds; pick speed 1 for the full length. Clips are the main cost, and they scale with length (the speed does not change the price).\nChoices:\n- 20 — 20 seconds: 20 seconds of clips: a film of about 18 seconds at the 1.1x speed a new film plays at, 20 seconds at 1x.\n- 30 — 30 seconds: 30 seconds of clips: a film of about 27 seconds at the 1.1x speed a new film plays at, 30 seconds at 1x.\n- 40 — 40 seconds: 40 seconds of clips: a film of about 36 seconds at the 1.1x speed a new film plays at, 40 seconds at 1x.\n- 50 — 50 seconds: 50 seconds of clips: a film of about 45 seconds at the 1.1x speed a new film plays at, 50 seconds at 1x.\n- 60 — 60 seconds: 60 seconds of clips: a film of about 55 seconds at the 1.1x speed a new film plays at, 60 seconds at 1x.\n- 70 — 70 seconds: 70 seconds of clips: a film of about 64 seconds at the 1.1x speed a new film plays at, 70 seconds at 1x.\n- 80 — 80 seconds: 80 seconds of clips: a film of about 73 seconds at the 1.1x speed a new film plays at, 80 seconds at 1x.\n- 90 — 90 seconds: 90 seconds of clips: a film of about 82 seconds at the 1.1x speed a new film plays at, 90 seconds at 1x.\nDefault: 30.","type":"string","enum":["20","30","40","50","60","70","80","90"]},{"type":"number","enum":[20,30,40,50,60,70,80,90]}]},"aspectRatio":{"description":"Frame: The shape of the film.\nChoices:\n- 9:16 — 9:16: Tall, for TikTok, Reels and Shorts.\n- 16:9 — 16:9: Wide, for YouTube.\n- 1:1 — 1:1: Square.\n- 4:3 — 4:3: Classic TV shape.\n- 3:4 — 3:4: Portrait photo shape.\nDefault: 9:16.","type":"string","enum":["9:16","16:9","1:1","4:3","3:4"]},"quality":{"description":"Quality: Clips render at 720p. \"1080p\" adds a free AI upscale at the same price.\nChoices:\n- 1080p — 1080p: Rendered at 720p, then upscaled to 1080p for free.\n- 720p — 720p: Rendered and delivered at 720p.\nDefault: 1080p.","type":"string","enum":["1080p","720p"]},"nativeAudio":{"description":"Voices and sound in the clips: the video model speaks the lines and adds sound. It stays on when characters talk (every new Studio film lets the writer decide who speaks), so only an older narrated or wordless project can turn it off. Default: true.","type":"boolean"},"musicSource":{"description":"Soundtrack: Where the music comes from.\nChoices:\n- studio — Studio soundtrack: An AI soundtrack written for the story. (36 credits per soundtrack take)\n- native — Scored inside the clip: The video model scores the clip itself. Only for a single clip of 30 seconds or less with native audio on.\nDefault: studio.","type":"string","enum":["studio","native"]},"webSearch":{"description":"Web search: let the writer read the web for facts and trends. Adds a few credits per script request. Default: false.","type":"boolean"},"enhanceBrief":{"description":"Improve my idea first: turn a short idea into a full brief before the script is written (free). Only the app does this, when the script is started there; Autopilot never reads this switch, so studio_autopilot start writes from your idea as you typed it (or from an improved version the app already made). Default: true.","type":"boolean"},"inSceneText":{"description":"Text inside the scene: signs, screens and labels the video model draws inside the picture. Default: true.","type":"boolean"},"textOnTop":{"description":"Text on top: titles, messages, labels and an end card drawn over the finished video (free, editable afterwards). Default: true.","type":"boolean"},"imageModel":{"description":"Picture maker: Which model draws the characters, places, objects and character sheets.\nChoices:\n- dream5 — Dream 5: Recommended for polished 3D character and asset references. (41 credits per picture)\n- gptImage2High — ChatGPT Image 2.0 High: Strong prompt accuracy and crisp production detail. (30 credits per picture)\n- nanoBanana2 — Nano Banana 2: Fast high-quality generations with flexible references. (72 credits per picture)\nDefault: dream5.","type":"string","enum":["dream5","gptImage2High","nanoBanana2"]},"whoSpeaks":{"description":"Who speaks: Who says the words: the writer decides (auto), only the characters, only a narrator, or nobody. A fixed choice is guaranteed; it shapes the brief and the script.\nChoices:\n- auto — Auto: A narrator, the characters, or both. The writer picks whatever keeps people watching.\n- characters — Only the characters: No narrator. Every word is said on screen by a character.\n- narrator — Only a narrator: A voice-over tells the story. The characters never speak.\n- none — No one: No talking at all. The story is told with action, sound and music.\nDefault: auto.","type":"string","enum":["auto","characters","narrator","none"]},"attachments":{"description":"Up to 16 pictures from your media library for the writer to look at (each once).","maxItems":16,"type":"array","items":{"type":"object","properties":{"mediaId":{"description":"A picture in your media library (autoclips_media list, upload_link or import_url).","type":"string","pattern":"^[a-fA-F0-9]{24}$"}},"required":["mediaId"],"additionalProperties":false}}},"required":["idea"],"additionalProperties":false},"example":{"idea":"A tiny robot tries to return a lost star to the sky","durationSeconds":"30","aspectRatio":"9:16"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"studio"},"title":{"description":"The film's name: the script's title once there is one, unless the project was given a name of its own. Until it is renamed, the app's history list may still show the first words of the idea.","type":"string"},"status":{"description":"How far the film got: new (Just an idea so far); brainstorming (Idea saved, no script yet); research_ready (Trend ideas found, no script yet); script_ready (Script written); film_ready (Film ready). film_ready while the project holds a finished video (video); stage says where the film is in more detail.","type":"string"},"stage":{"description":"Where the film is, in plain words: an open Autopilot run and its step, else \"Film ready\" with its length, else how many clips are made, else the status.","type":"string"},"mode":{"description":"director = made step by step; autopilot = Autopilot makes the whole film.","type":"string","enum":["director","autopilot"]},"step":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"settings":{"description":"The settings, in the same words create and update take.","type":"object","properties":{},"additionalProperties":{}},"idea":{"anyOf":[{"type":"string"},{"type":"null"}]},"counts":{"type":"object","properties":{},"additionalProperties":{}},"video":{"description":"The finished film, once there is one.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"autopilot":{"description":"The Autopilot run, when one was started.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"openInApp":{"description":"True while an app tab is editing the project (it saved in the last 90 seconds). The API cannot change it until that tab has been still for 90 seconds or is closed.","type":"boolean"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"app":{"type":"string"},"editor":{"type":"string"}},"required":["app","editor"],"additionalProperties":{}}},"required":["id","product","title","status","stage","mode","step","durationSeconds","settings","idea","counts","video","autopilot","openInApp","createdAt","updatedAt","links"],"additionalProperties":{}}},"required":["project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19","product":"studio","title":"A tiny robot tries to return a lost star to the sky","status":"brainstorming","stage":"Idea saved, no script yet","mode":"director","step":"script-analysis","durationSeconds":30,"settings":{"writerModel":"trendScout","webSearch":false,"aspectRatio":"9:16","quality":"1080p","nativeAudio":true,"imageModel":"dream5","inSceneText":true,"textOnTop":true,"whoSpeaks":"auto","musicSource":"studio","productionModel":"trendScout","enhanceBrief":true,"speed":1.1},"idea":"A tiny robot tries to return a lost star to the sky","counts":{"scenes":0,"characters":0,"assets":0,"clips":0,"clipsReady":0,"finalVideos":0},"video":null,"autopilot":null,"openInApp":false,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","links":{"app":"https://app.autoclips.app/studio-2?projectId=9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19","editor":"https://app.autoclips.app/editor/9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}":{"get":{"operationId":"studio_projects_get","summary":"One Studio project: status, settings, film link, and on request its script, cast, clips, videos and more.","description":"Opens one of your Studio 2.0 projects. Add include to see more: script, cast, clips, videos, soundtrack, publishing, autopilot (for example include=script,clips). Without include you get the status, settings, counts, the finished film when there is one, the Autopilot run, and links to open it in the app.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"studio.projects.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_projects action=get","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from list or create).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"include","in":"query","required":false,"schema":{"description":"Extra sections: script, cast, clips, videos, soundtrack, publishing, autopilot. script = every scene's words and action; cast = characters, objects and places with their pictures; clips = the clip cards and their videos; videos = every finished cut; soundtrack = music; publishing = titles, captions and posts.","maxItems":7,"type":"array","items":{"type":"string","enum":["script","cast","clips","videos","soundtrack","publishing","autopilot"]}},"description":"Extra sections: script, cast, clips, videos, soundtrack, publishing, autopilot. script = every scene's words and action; cast = characters, objects and places with their pictures; clips = the clip cards and their videos; videos = every finished cut; soundtrack = music; publishing = titles, captions and posts.","example":["script","clips"]}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"studio"},"title":{"description":"The film's name: the script's title once there is one, unless the project was given a name of its own. Until it is renamed, the app's history list may still show the first words of the idea.","type":"string"},"status":{"description":"How far the film got: new (Just an idea so far); brainstorming (Idea saved, no script yet); research_ready (Trend ideas found, no script yet); script_ready (Script written); film_ready (Film ready). film_ready while the project holds a finished video (video); stage says where the film is in more detail.","type":"string"},"stage":{"description":"Where the film is, in plain words: an open Autopilot run and its step, else \"Film ready\" with its length, else how many clips are made, else the status.","type":"string"},"mode":{"description":"director = made step by step; autopilot = Autopilot makes the whole film.","type":"string","enum":["director","autopilot"]},"step":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"settings":{"description":"The settings, in the same words create and update take.","type":"object","properties":{},"additionalProperties":{}},"idea":{"anyOf":[{"type":"string"},{"type":"null"}]},"counts":{"type":"object","properties":{},"additionalProperties":{}},"video":{"description":"The finished film, once there is one.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"autopilot":{"description":"The Autopilot run, when one was started.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"openInApp":{"description":"True while an app tab is editing the project (it saved in the last 90 seconds). The API cannot change it until that tab has been still for 90 seconds or is closed.","type":"boolean"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"app":{"type":"string"},"editor":{"type":"string"}},"required":["app","editor"],"additionalProperties":{}}},"required":["id","product","title","status","stage","mode","step","durationSeconds","settings","idea","counts","video","autopilot","openInApp","createdAt","updatedAt","links"],"additionalProperties":{}}},"required":["project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"studio_projects_update","summary":"Change a Studio project's settings or name. Some settings lock once the script or the clips exist.","description":"Changes the settings you send (and the name). Free. These choices are used when Autopilot makes the film (studio_autopilot start uses them unless you send others), and the app shows them in its Autopilot panel. The one exception is enhanceBrief (improve my idea first): Autopilot never reads it, so studio_autopilot start writes from your idea as you typed it (or from an improved version the app already made); it only counts when the script is started in the app. If you direct the film step by step in the app instead, you pick the frame, quality, voices and sound, and picture maker again in its later steps. Before a script exists every setting can change. Once the script is written, the settings that shaped it (writer, planning AI, length, soundtrack, web search, improve my idea first, text inside the scene) are locked; frame, quality, voices and sound, picture maker and text on top can still change. Once the clips are planned, frame and voices and sound are locked too (changing them clears the planned clips, which only the app does). Refused while an app tab is editing the project (it saved in the last 90 seconds), and, for settings, while Autopilot is making it or while Studio is working on it (a step, a clip, the final film, a soundtrack, a watermark, end card or thumbnail, or an edited cut). An app tab that had the project open before this change keeps the new values, unless the person changes that same setting there afterwards. One exception: if the first change made in a tab opened after an API change puts that setting back to a value it had before, the API's value stays; to avoid it, change something else in that tab first, or pick a different value and then the old one. The app shows this name in its history list and keeps it: saving in the app no longer renames the project after its script. A film shown as a public sample cannot be renamed.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.projects.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_projects action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"The project name (up to 80 characters), as it shows in the app's history list.","type":"string","minLength":1,"maxLength":80},"writerModel":{"description":"Writer: Which AI writes the brief and the script. Billed at the real AI cost after each request. Every writer is offered on every plan; a new project starts on the app's pick for your plan.\nChoices:\n- opus55 — Claude Opus 5.5: Strongest physical logic and continuity for demanding stories. A 30-second script costs about 210 credits, a longer one more (billed at the real AI cost).\n- trendScout — Kimi K3: Strong, timely, research-led story development. A 30-second script costs about 158 credits, a longer one more (billed at the real AI cost).\n- quickSpark — Gemini 3.8 Flash: Fast brainstorming with clear visual beats. A 30-second script costs about 36 credits, a longer one more (billed at the real AI cost).\nDefault: the project's current writer (leave it out).","type":"string","enum":["opus55","trendScout","quickSpark"]},"productionModel":{"description":"Planning AI: Which AI plans the pictures, character sheets and clips from the script (it looks at the pictures, so only vision-capable writers). A new project starts on the app's pick for your plan.\nChoices:\n- opus55 — Claude Opus 5.5: Strongest physical logic and continuity for demanding stories. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 783 credits, a longer film or a bigger cast more (billed at the real AI cost).\n- trendScout — Kimi K3: Strong, timely, research-led story development. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 589 credits, a longer film or a bigger cast more (billed at the real AI cost).\n- quickSpark — Gemini 3.8 Flash: Fast brainstorming with clear visual beats. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 150 credits, a longer film or a bigger cast more (billed at the real AI cost).\nDefault: the project's current planning AI (leave it out).","type":"string","enum":["opus55","trendScout","quickSpark"]},"durationSeconds":{"description":"Length: How many seconds of story are written and rendered as clips. The finished film lasts that divided by its speed: a new film plays at 1.1x, so 30 seconds of clips make a film of about 27 seconds; pick speed 1 for the full length. Clips are the main cost, and they scale with length (the speed does not change the price).\nChoices:\n- 20 — 20 seconds: 20 seconds of clips: a film of about 18 seconds at the 1.1x speed a new film plays at, 20 seconds at 1x.\n- 30 — 30 seconds: 30 seconds of clips: a film of about 27 seconds at the 1.1x speed a new film plays at, 30 seconds at 1x.\n- 40 — 40 seconds: 40 seconds of clips: a film of about 36 seconds at the 1.1x speed a new film plays at, 40 seconds at 1x.\n- 50 — 50 seconds: 50 seconds of clips: a film of about 45 seconds at the 1.1x speed a new film plays at, 50 seconds at 1x.\n- 60 — 60 seconds: 60 seconds of clips: a film of about 55 seconds at the 1.1x speed a new film plays at, 60 seconds at 1x.\n- 70 — 70 seconds: 70 seconds of clips: a film of about 64 seconds at the 1.1x speed a new film plays at, 70 seconds at 1x.\n- 80 — 80 seconds: 80 seconds of clips: a film of about 73 seconds at the 1.1x speed a new film plays at, 80 seconds at 1x.\n- 90 — 90 seconds: 90 seconds of clips: a film of about 82 seconds at the 1.1x speed a new film plays at, 90 seconds at 1x.\nDefault: the project's current length (leave it out).","anyOf":[{"description":"Length: How many seconds of story are written and rendered as clips. The finished film lasts that divided by its speed: a new film plays at 1.1x, so 30 seconds of clips make a film of about 27 seconds; pick speed 1 for the full length. Clips are the main cost, and they scale with length (the speed does not change the price).\nChoices:\n- 20 — 20 seconds: 20 seconds of clips: a film of about 18 seconds at the 1.1x speed a new film plays at, 20 seconds at 1x.\n- 30 — 30 seconds: 30 seconds of clips: a film of about 27 seconds at the 1.1x speed a new film plays at, 30 seconds at 1x.\n- 40 — 40 seconds: 40 seconds of clips: a film of about 36 seconds at the 1.1x speed a new film plays at, 40 seconds at 1x.\n- 50 — 50 seconds: 50 seconds of clips: a film of about 45 seconds at the 1.1x speed a new film plays at, 50 seconds at 1x.\n- 60 — 60 seconds: 60 seconds of clips: a film of about 55 seconds at the 1.1x speed a new film plays at, 60 seconds at 1x.\n- 70 — 70 seconds: 70 seconds of clips: a film of about 64 seconds at the 1.1x speed a new film plays at, 70 seconds at 1x.\n- 80 — 80 seconds: 80 seconds of clips: a film of about 73 seconds at the 1.1x speed a new film plays at, 80 seconds at 1x.\n- 90 — 90 seconds: 90 seconds of clips: a film of about 82 seconds at the 1.1x speed a new film plays at, 90 seconds at 1x.\nDefault: the project's current length (leave it out).","type":"string","enum":["20","30","40","50","60","70","80","90"]},{"type":"number","enum":[20,30,40,50,60,70,80,90]}]},"aspectRatio":{"description":"Frame: The shape of the film.\nChoices:\n- 9:16 — 9:16: Tall, for TikTok, Reels and Shorts.\n- 16:9 — 16:9: Wide, for YouTube.\n- 1:1 — 1:1: Square.\n- 4:3 — 4:3: Classic TV shape.\n- 3:4 — 3:4: Portrait photo shape.\nDefault: the project's current frame (leave it out).","type":"string","enum":["9:16","16:9","1:1","4:3","3:4"]},"quality":{"description":"Quality: Clips render at 720p. \"1080p\" adds a free AI upscale at the same price.\nChoices:\n- 1080p — 1080p: Rendered at 720p, then upscaled to 1080p for free.\n- 720p — 720p: Rendered and delivered at 720p.\nDefault: the project's current quality (leave it out).","type":"string","enum":["1080p","720p"]},"nativeAudio":{"description":"Voices and sound in the clips: the video model speaks the lines and adds sound. It stays on when characters talk (every new Studio film lets the writer decide who speaks), so only an older narrated or wordless project can turn it off. Default: the project's current setting (leave it out).","type":"boolean"},"musicSource":{"description":"Soundtrack: Where the music comes from.\nChoices:\n- studio — Studio soundtrack: An AI soundtrack written for the story. (36 credits per soundtrack take)\n- native — Scored inside the clip: The video model scores the clip itself. Only for a single clip of 30 seconds or less with native audio on.\nDefault: the project's current soundtrack (leave it out).","type":"string","enum":["studio","native"]},"webSearch":{"description":"Web search: let the writer read the web for facts and trends. Adds a few credits per script request. Default: the project's current setting (leave it out).","type":"boolean"},"enhanceBrief":{"description":"Improve my idea first: turn a short idea into a full brief before the script is written (free). Only the app does this, when the script is started there; Autopilot never reads this switch, so studio_autopilot start writes from your idea as you typed it (or from an improved version the app already made). Default: the project's current setting (leave it out).","type":"boolean"},"inSceneText":{"description":"Text inside the scene: signs, screens and labels the video model draws inside the picture. Default: the project's current setting (leave it out).","type":"boolean"},"textOnTop":{"description":"Text on top: titles, messages, labels and an end card drawn over the finished video (free, editable afterwards). Default: the project's current setting (leave it out).","type":"boolean"},"imageModel":{"description":"Picture maker: Which model draws the characters, places, objects and character sheets.\nChoices:\n- dream5 — Dream 5: Recommended for polished 3D character and asset references. (41 credits per picture)\n- gptImage2High — ChatGPT Image 2.0 High: Strong prompt accuracy and crisp production detail. (30 credits per picture)\n- nanoBanana2 — Nano Banana 2: Fast high-quality generations with flexible references. (72 credits per picture)\nDefault: the project's current picture maker (leave it out).","type":"string","enum":["dream5","gptImage2High","nanoBanana2"]},"whoSpeaks":{"description":"Who speaks: Who says the words: the writer decides (auto), only the characters, only a narrator, or nobody. A fixed choice is guaranteed; it shapes the brief and the script.\nChoices:\n- auto — Auto: A narrator, the characters, or both. The writer picks whatever keeps people watching.\n- characters — Only the characters: No narrator. Every word is said on screen by a character.\n- narrator — Only a narrator: A voice-over tells the story. The characters never speak.\n- none — No one: No talking at all. The story is told with action, sound and music.\nDefault: the project's current who speaks (leave it out).","type":"string","enum":["auto","characters","narrator","none"]}},"additionalProperties":false},"example":{"aspectRatio":"16:9","durationSeconds":"60"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from list or create).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"studio"},"title":{"description":"The film's name: the script's title once there is one, unless the project was given a name of its own. Until it is renamed, the app's history list may still show the first words of the idea.","type":"string"},"status":{"description":"How far the film got: new (Just an idea so far); brainstorming (Idea saved, no script yet); research_ready (Trend ideas found, no script yet); script_ready (Script written); film_ready (Film ready). film_ready while the project holds a finished video (video); stage says where the film is in more detail.","type":"string"},"stage":{"description":"Where the film is, in plain words: an open Autopilot run and its step, else \"Film ready\" with its length, else how many clips are made, else the status.","type":"string"},"mode":{"description":"director = made step by step; autopilot = Autopilot makes the whole film.","type":"string","enum":["director","autopilot"]},"step":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"settings":{"description":"The settings, in the same words create and update take.","type":"object","properties":{},"additionalProperties":{}},"idea":{"anyOf":[{"type":"string"},{"type":"null"}]},"counts":{"type":"object","properties":{},"additionalProperties":{}},"video":{"description":"The finished film, once there is one.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"autopilot":{"description":"The Autopilot run, when one was started.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"openInApp":{"description":"True while an app tab is editing the project (it saved in the last 90 seconds). The API cannot change it until that tab has been still for 90 seconds or is closed.","type":"boolean"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"app":{"type":"string"},"editor":{"type":"string"}},"required":["app","editor"],"additionalProperties":{}}},"required":["id","product","title","status","stage","mode","step","durationSeconds","settings","idea","counts","video","autopilot","openInApp","createdAt","updatedAt","links"],"additionalProperties":{}},"changed":{"description":"The fields that really changed (a value equal to the saved one changes nothing).","type":"array","items":{"type":"string"}}},"required":["project","changed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"studio_projects_delete","summary":"Delete a Studio project for good. This cannot be undone. Not while it is being made or is open in the app.","description":"Deletes the project: its idea, script, cast, clip cards, finished cuts and settings disappear from the app. This cannot be undone. Pictures, clips and films already made stay in storage (links you saved keep working), as for other AutoClips videos; credits already spent are not returned. Refused for a film shown as a public sample; while Autopilot is making it; while Studio is working on it (a step, a clip, the final film, a soundtrack, a watermark, end card or thumbnail, or an edited cut: paid work would be lost); and while an app tab is editing it (it saved in the last 90 seconds): close that tab first. An app tab left open on the project cannot save it again afterwards: it shows its work as not saved. In an AI app it asks first, showing what goes (clips, finished cuts) and what is still running (Autopilot, finishing jobs).\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"studio.projects.delete","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_projects action=delete","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from list or create).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"projectId":{"type":"string"},"title":{"type":"string"}},"required":["deleted","projectId","title"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"deleted":true,"projectId":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19","title":"A tiny robot tries to return a lost star to the sky"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/attachments":{"post":{"operationId":"studio_attachments_add","summary":"Attach a text or Markdown file (notes, a brief, a script draft) for the writer to read. Before the script is written. Free.","description":"Attaches your text to the project as a file the writer reads when it writes the script, exactly like attaching a .txt or .md file in the app's composer. Send the text itself (up to 5 MB through the REST API; through MCP a whole request is 1 MB at most, so about 900 KB of text there) and, if you like, a file name (ending .txt or .md; default pasted-text.txt). Up to 16 text files per project, 10 MB together. Free; counts toward the daily limit for uploads and imports. Only before the script is written: afterwards the writer never reads attachments again. Refused while an app tab is editing the project (it saved in the last 90 seconds) and while anything runs on it (a step or Autopilot). The writer reads it when the script is written (studio_autopilot start, or the app's next script). An improved brief made before this is set aside, since it was written without this file. An app tab that had the project open before this change keeps the file when it saves, unless the person changes the attached files in that tab (then that tab's own list is saved). One gap: in a tab opened after this change, removing this file as the very first change there does not stick; make any other change in that tab first.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.attachments.add","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_projects action=attach_text","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"description":"The file's text (plain text or Markdown): up to 5 MB through the REST API. Through MCP a whole request is 1 MB at most, so send up to about 900 KB of text there; for more, use the REST API.","type":"string","minLength":1,"maxLength":5242880},"name":{"description":"The file name, ending .txt or .md (\".txt\" is added otherwise). Default: pasted-text.txt.","type":"string","minLength":1,"maxLength":120,"pattern":"^[^\\u0000-\\u001f\\u007f\\u202A-\\u202E\\u2066-\\u2069]+$"}},"required":["text"],"additionalProperties":false},"example":{"name":"brief.md","text":"# Oat milk launch\nOur owl mascot hates change. Keep it under 30 seconds and end on the logo."}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from list or create).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"attachment":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"sizeBytes":{"type":"number"}},"required":["id","name","sizeBytes"],"additionalProperties":false},"textFiles":{"description":"Every text file attached to the project now.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"sizeBytes":{"type":"number"}},"required":["id","name","sizeBytes"],"additionalProperties":false}},"pictures":{"description":"How many pictures are attached as well.","type":"number"},"note":{"type":"string"}},"required":["projectId","attachment","textFiles","pictures","note"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e","attachment":{"id":"text-4b7a1c2d-9e8f-4a6b-8c1d-2e3f4a5b6c7d","name":"brief.md","sizeBytes":92},"textFiles":[{"id":"text-4b7a1c2d-9e8f-4a6b-8c1d-2e3f4a5b6c7d","name":"brief.md","sizeBytes":92}],"pictures":0,"note":"The writer reads it when the script is written (studio_autopilot start, or the app's next script). An improved brief made before this is set aside, since it was written without this file. An app tab that had the project open before this change keeps the file when it saves, unless the person changes the attached files in that tab (then that tab's own list is saved). One gap: in a tab opened after this change, removing this file as the very first change there does not stick; make any other change in that tab first."}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/autopilot":{"post":{"operationId":"studio_autopilot_start","summary":"Make the whole film automatically. Paid: what you approve is its spending limit (one step's final cost can run a little over).","description":"Starts Autopilot on a project that has an idea or a script: it writes the script (unless there is one), makes the characters, places and objects, the character sheets, plans and renders every clip, adds the soundtrack and cuts the final video. Settings you leave out keep the project's saved Autopilot choices (the approval shows every setting). What you approve is the top of the estimate for these settings and the project's cast, and it becomes the run's spending limit. Autopilot stops before a step that would go past the limit; one step's final cost can run a little over. Each step is charged as it happens, so it usually costs less; if the film needs more than you approved, the run pauses at needs_cap and asks (raise_cap). It answers with a job at once (status 202); follow it with autoclips_jobs get or status. A project can have one open run at a time, and it cannot start while the project is open in the app or other work runs on it.\n\n**Permissions:** edit, spend.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. Autopilot stops before a step that would go past the limit, but one step's final cost can run a little over, so the limit is not the most it can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"studio.autopilot.start","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"studio_autopilot action=start","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"description":"How Autopilot makes the film. Every field is optional: one you leave out keeps the choice saved on the project for Autopilot (what the app's Autopilot panel shows), else the app's default; the length is the project's. quote answers the settings it will use. See studio options for every choice.","type":"object","properties":{"durationSeconds":{"description":"Length: How many seconds of story are written and rendered as clips. The finished film lasts that divided by its speed: a new film plays at 1.1x, so 30 seconds of clips make a film of about 27 seconds; pick speed 1 for the full length. Clips are the main cost, and they scale with length (the speed does not change the price).\nChoices:\n- 20 — 20 seconds: 20 seconds of clips: a film of about 18 seconds at the 1.1x speed a new film plays at, 20 seconds at 1x.\n- 30 — 30 seconds: 30 seconds of clips: a film of about 27 seconds at the 1.1x speed a new film plays at, 30 seconds at 1x.\n- 40 — 40 seconds: 40 seconds of clips: a film of about 36 seconds at the 1.1x speed a new film plays at, 40 seconds at 1x.\n- 50 — 50 seconds: 50 seconds of clips: a film of about 45 seconds at the 1.1x speed a new film plays at, 50 seconds at 1x.\n- 60 — 60 seconds: 60 seconds of clips: a film of about 55 seconds at the 1.1x speed a new film plays at, 60 seconds at 1x.\n- 70 — 70 seconds: 70 seconds of clips: a film of about 64 seconds at the 1.1x speed a new film plays at, 70 seconds at 1x.\n- 80 — 80 seconds: 80 seconds of clips: a film of about 73 seconds at the 1.1x speed a new film plays at, 80 seconds at 1x.\n- 90 — 90 seconds: 90 seconds of clips: a film of about 82 seconds at the 1.1x speed a new film plays at, 90 seconds at 1x.\nDefault: the project's length, else 30 (leave it out).\nSend it as text (\"30\") or a number (30).","anyOf":[{"description":"Length: How many seconds of story are written and rendered as clips. The finished film lasts that divided by its speed: a new film plays at 1.1x, so 30 seconds of clips make a film of about 27 seconds; pick speed 1 for the full length. Clips are the main cost, and they scale with length (the speed does not change the price).\nChoices:\n- 20 — 20 seconds: 20 seconds of clips: a film of about 18 seconds at the 1.1x speed a new film plays at, 20 seconds at 1x.\n- 30 — 30 seconds: 30 seconds of clips: a film of about 27 seconds at the 1.1x speed a new film plays at, 30 seconds at 1x.\n- 40 — 40 seconds: 40 seconds of clips: a film of about 36 seconds at the 1.1x speed a new film plays at, 40 seconds at 1x.\n- 50 — 50 seconds: 50 seconds of clips: a film of about 45 seconds at the 1.1x speed a new film plays at, 50 seconds at 1x.\n- 60 — 60 seconds: 60 seconds of clips: a film of about 55 seconds at the 1.1x speed a new film plays at, 60 seconds at 1x.\n- 70 — 70 seconds: 70 seconds of clips: a film of about 64 seconds at the 1.1x speed a new film plays at, 70 seconds at 1x.\n- 80 — 80 seconds: 80 seconds of clips: a film of about 73 seconds at the 1.1x speed a new film plays at, 80 seconds at 1x.\n- 90 — 90 seconds: 90 seconds of clips: a film of about 82 seconds at the 1.1x speed a new film plays at, 90 seconds at 1x.\nDefault: the project's length, else 30 (leave it out).","type":"string","enum":["20","30","40","50","60","70","80","90"]},{"type":"number","enum":[20,30,40,50,60,70,80,90]}]},"aspectRatio":{"description":"Frame: The shape of the film.\nChoices:\n- 9:16 — 9:16: Tall, for TikTok, Reels and Shorts.\n- 16:9 — 16:9: Wide, for YouTube.\n- 1:1 — 1:1: Square.\n- 4:3 — 4:3: Classic TV shape.\n- 3:4 — 3:4: Portrait photo shape.\nDefault: the frame saved in the project's Autopilot panel, else 9:16 (leave it out).","type":"string","enum":["9:16","16:9","1:1","4:3","3:4"]},"quality":{"description":"Quality: Clips render at 720p. \"1080p\" adds a free AI upscale at the same price.\nChoices:\n- 1080p — 1080p: Rendered at 720p, then upscaled to 1080p for free.\n- 720p — 720p: Rendered and delivered at 720p.\nDefault: the quality saved in the project's Autopilot panel, else 1080p (leave it out).","type":"string","enum":["1080p","720p"]},"nativeAudio":{"description":"The video model speaks the lines and adds sound. Always on when characters talk. Default: the choice saved in the project's Autopilot panel, else on (leave it out).","type":"boolean"},"musicSource":{"description":"Soundtrack: Where the music comes from.\nChoices:\n- studio — Studio soundtrack: An AI soundtrack written for the story. (36 credits per soundtrack take)\n- native — Scored inside the clip: The video model scores the clip itself. Only for a single clip of 30 seconds or less with native audio on.\nDefault: the soundtrack saved in the project's Autopilot panel, else studio (leave it out).","type":"string","enum":["studio","native"]},"webSearch":{"description":"Let the writer read the web for facts and trends. Adds a few credits per request. Default: the choice saved in the project's Autopilot panel, else off (leave it out).","type":"boolean"},"writerModel":{"description":"Writer: Which AI writes the brief and the script. Billed at the real AI cost after each request. Every writer is offered on every plan; a new project starts on the app's pick for your plan.\nChoices:\n- opus55 — Claude Opus 5.5: Strongest physical logic and continuity for demanding stories. A 30-second script costs about 210 credits, a longer one more (billed at the real AI cost).\n- trendScout — Kimi K3: Strong, timely, research-led story development. A 30-second script costs about 158 credits, a longer one more (billed at the real AI cost).\n- quickSpark — Gemini 3.8 Flash: Fast brainstorming with clear visual beats. A 30-second script costs about 36 credits, a longer one more (billed at the real AI cost).\nDefault: the writer saved in the project's Autopilot panel, else the project's writer, else Kimi K3 (leave it out).","type":"string","enum":["opus55","trendScout","quickSpark"]},"productionModel":{"description":"Planning AI: Which AI plans the pictures, character sheets and clips from the script (it looks at the pictures, so only vision-capable writers). A new project starts on the app's pick for your plan.\nChoices:\n- opus55 — Claude Opus 5.5: Strongest physical logic and continuity for demanding stories. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 783 credits, a longer film or a bigger cast more (billed at the real AI cost).\n- trendScout — Kimi K3: Strong, timely, research-led story development. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 589 credits, a longer film or a bigger cast more (billed at the real AI cost).\n- quickSpark — Gemini 3.8 Flash: Fast brainstorming with clear visual beats. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 150 credits, a longer film or a bigger cast more (billed at the real AI cost).\nDefault: the planning AI saved in the project's Autopilot panel, else Kimi K3 (leave it out).","type":"string","enum":["opus55","trendScout","quickSpark"]},"imageModel":{"description":"Picture maker: Which model draws the characters, places, objects and character sheets.\nChoices:\n- dream5 — Dream 5: Recommended for polished 3D character and asset references. (41 credits per picture)\n- gptImage2High — ChatGPT Image 2.0 High: Strong prompt accuracy and crisp production detail. (30 credits per picture)\n- nanoBanana2 — Nano Banana 2: Fast high-quality generations with flexible references. (72 credits per picture)\nDefault: the picture maker saved in the project's Autopilot panel, else dream5 (leave it out).","type":"string","enum":["dream5","gptImage2High","nanoBanana2"]},"inSceneText":{"description":"Signs, screens and labels the video model draws inside the picture. Default: the choice saved in the project's Autopilot panel, else on (leave it out).","type":"boolean"},"textOnTop":{"description":"Titles, chat messages, labels and an end card drawn over the finished video (free, editable afterwards). Default: the choice saved in the project's Autopilot panel, else on (leave it out).","type":"boolean"},"whoSpeaks":{"description":"Who speaks: Who says the words: the writer decides (auto), only the characters, only a narrator, or nobody. A fixed choice is guaranteed; it shapes the brief and the script.\nChoices:\n- auto — Auto: A narrator, the characters, or both. The writer picks whatever keeps people watching.\n- characters — Only the characters: No narrator. Every word is said on screen by a character.\n- narrator — Only a narrator: A voice-over tells the story. The characters never speak.\n- none — No one: No talking at all. The story is told with action, sound and music.\nDefault: the who speaks saved in the project's Autopilot panel, else auto (leave it out).","type":"string","enum":["auto","characters","narrator","none"]},"speed":{"description":"Final video speed: How fast the finished video plays. Every clip plays faster with its voices at their own pitch; the soundtrack and the outro stay at normal speed. A finished video lasts its clips' seconds divided by the speed. Free: clips are priced by the seconds rendered, which the speed does not change. A film joined before speeds existed stays at 1x until a speed is chosen.\nChoices:\n- 1 — 1x: Normal speed, as the clips were rendered. (Free)\n- 1.1 — 1.1x: A little quicker than rendered. What a new film plays at. (Free)\n- 1.25 — 1.25x: Recommended: the quick pace short-form edits use. (Free)\n- 1.5 — 1.5x: 1.5 times as fast as rendered. (Free)\n- 2 — 2x: 2 times as fast as rendered. (Free)\nDefault: the speed saved in the project's Autopilot panel, else 1.1x (leave it out).\nSend the value as text (\"1.25\") or a number (1.25).\nAutopilot joins the film at this speed and saves it on the film, in place of the speed the film had.","anyOf":[{"description":"Final video speed: How fast the finished video plays. Every clip plays faster with its voices at their own pitch; the soundtrack and the outro stay at normal speed. A finished video lasts its clips' seconds divided by the speed. Free: clips are priced by the seconds rendered, which the speed does not change. A film joined before speeds existed stays at 1x until a speed is chosen.\nChoices:\n- 1 — 1x: Normal speed, as the clips were rendered. (Free)\n- 1.1 — 1.1x: A little quicker than rendered. What a new film plays at. (Free)\n- 1.25 — 1.25x: Recommended: the quick pace short-form edits use. (Free)\n- 1.5 — 1.5x: 1.5 times as fast as rendered. (Free)\n- 2 — 2x: 2 times as fast as rendered. (Free)\nDefault: the speed saved in the project's Autopilot panel, else 1.1x (leave it out).","type":"string","enum":["1","2","1.1","1.25","1.5"]},{"type":"number","enum":[1,1.1,1.25,1.5,2]}]}},"additionalProperties":false},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio 2.0 project id (from studio projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio 2.0 project id (from studio projects list or create).","example":"4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job":{"description":"Follow it with autoclips_jobs get. It succeeds with result.finalVideoUrl when the film is ready.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"run":{"type":"object","properties":{"runId":{"type":"string"},"projectId":{"type":"string"},"status":{"description":"running, retrying, pausing, paused, needs_cap, needs_credits, needs_attention, completed, cancelled or taken_over.","type":"string","enum":["running","retrying","pausing","paused","needs_cap","needs_credits","needs_attention","completed","cancelled","taken_over"]},"statusWords":{"type":"string"},"stage":{"type":"string"},"stageLabel":{"type":"string"},"progress":{"type":"number","minimum":0,"maximum":100},"completedItems":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalItems":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"message":{"type":"string"},"creditsCharged":{"description":"Credits charged so far.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"creditsAuthorized":{"description":"Credits held for the step running now.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"spendingCapCredits":{"description":"The run's spending limit. Autopilot stops before a step that would go past the limit; one step's final cost can run a little over. It then waits at needs_cap.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ownLimit":{"description":"False when the run was started in the app: it has no spending limit of its own (spendingCapCredits shows 10,000,000) and your balance is its only limit. Set one with raise_cap.","type":"boolean"},"estimatedCredits":{"anyOf":[{"type":"object","properties":{"lower":{"description":"The least it is likely to cost.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"upper":{"description":"The top of the estimate for these settings; start asks you to approve this as the spending limit.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expected":{"description":"About what it usually costs.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["lower","upper","expected"],"additionalProperties":false},{"type":"null"}]},"settings":{"type":"object","properties":{"durationSeconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"storyMode":{"description":"How the story is told: mixed (the writer decides), narrated, dialogue or wordless. Set by the project.","type":"string"},"aspectRatio":{"type":"string"},"quality":{"type":"string"},"nativeAudio":{"type":"boolean"},"musicSource":{"type":"string"},"webSearch":{"type":"boolean"},"writerModel":{"type":"string"},"productionModel":{"type":"string"},"imageModel":{"type":"string"},"inSceneText":{"type":"boolean"},"textOnTop":{"type":"boolean"},"whoSpeaks":{"description":"Who says the words: auto (the writer decides), characters, narrator or none.","type":"string"},"speed":{"description":"How fast the finished video plays (1 = as rendered; voices keep their pitch, the soundtrack and outro stay at normal speed). Free.","type":"number"}},"required":["durationSeconds","storyMode","aspectRatio","quality","nativeAudio","musicSource","webSearch","writerModel","productionModel","imageModel","inSceneText","textOnTop","whoSpeaks","speed"],"additionalProperties":false},"outputs":{"type":"object","properties":{"characters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","url","createdAt"],"additionalProperties":false}},"assets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","url","createdAt"],"additionalProperties":false}},"characterSheets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","url","createdAt"],"additionalProperties":false}}},"required":["characters","assets","characterSheets"],"additionalProperties":false},"stale":{"description":"Set when the run looks stuck; retry it with control retry_stuck.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"retryCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"attention":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requiredCredits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["code","message","requiredCredits"],"additionalProperties":false},{"type":"null"}]},"pauseRequested":{"type":"boolean"},"nextStep":{"description":"What happens next, or what you need to do, in plain words.","type":"string"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["runId","projectId","status","statusWords","stage","stageLabel","progress","completedItems","totalItems","message","creditsCharged","creditsAuthorized","spendingCapCredits","ownLimit","estimatedCredits","settings","outputs","stale","retryCount","attention","pauseRequested","nextStep","createdAt","updatedAt","completedAt"],"additionalProperties":false},"project":{"description":"The project, in the same shape as reading it with studio projects get.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"studio"},"title":{"type":"string"},"status":{"type":"string"},"video":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":{}},{"type":"null"}]},"links":{"type":"object","properties":{"app":{"type":"string"},"editor":{"type":"string"}},"required":["app","editor"],"additionalProperties":false}},"required":["id","product","title","status","video","links"],"additionalProperties":{}},"approvedCredits":{"description":"The amount you approved: the run's spending limit. Nothing is charged yet; each step is charged as it happens.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"estimate":{"type":"object","properties":{"lower":{"description":"The least it is likely to cost.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"upper":{"description":"The top of the estimate for these settings; start asks you to approve this as the spending limit.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expected":{"description":"About what it usually costs.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["lower","upper","expected"],"additionalProperties":false}},"required":["job","run","project","approvedCredits","estimate"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"job":{"id":"job_0199a2b3c4d5e6f708192a3b","product":"studio","kind":"studio.autopilot","resource":{"type":"project","id":"4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01"},"status":"running","step":"Script analysis","progress":0,"result":null,"error":null,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","finishedAt":null,"poll_after_seconds":15,"usualSeconds":1800},"run":{"runId":"e3a1c2b4-5d6f-4a7b-8c9d-0e1f2a3b4c5d","projectId":"4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01","status":"running","statusWords":"working","stage":"script","stageLabel":"Script analysis","progress":0,"completedItems":0,"totalItems":1,"message":"Preparing the script","creditsCharged":0,"creditsAuthorized":0,"spendingCapCredits":5384,"ownLimit":true,"estimatedCredits":{"lower":3741,"upper":5384,"expected":5088},"settings":{"durationSeconds":30,"storyMode":"mixed","aspectRatio":"9:16","quality":"1080p","nativeAudio":true,"musicSource":"studio","webSearch":false,"writerModel":"trendScout","productionModel":"trendScout","imageModel":"dream5","inSceneText":true,"textOnTop":true,"whoSpeaks":"auto","speed":1.1},"outputs":{"characters":[],"assets":[],"characterSheets":[]},"stale":{"code":"stalled_action","message":"No worker is handling this overdue action. Retry from the last safe checkpoint."},"retryCount":0,"attention":null,"pauseRequested":false,"nextStep":"Autopilot looks stuck on this step. Retry it with control retry_stuck.","createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","completedAt":null},"project":{"id":"4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01","product":"studio","title":"The Moon Cat","status":"draft","mode":"autopilot","step":null,"durationSeconds":30,"settings":{"writerModel":null,"webSearch":false,"aspectRatio":"9:16","quality":"1080p","nativeAudio":true,"imageModel":null,"productionModel":null,"inSceneText":true,"textOnTop":true,"whoSpeaks":"auto","musicSource":"studio","enhanceBrief":true,"speed":1.1},"idea":"A cat who builds a rocket to reach the moon","counts":{"scenes":0,"characters":0,"assets":0,"clips":0,"clipsReady":0,"finalVideos":0},"video":null,"autopilot":{"runId":"e3a1c2b4-5d6f-4a7b-8c9d-0e1f2a3b4c5d","status":"running","stage":"script","progress":0,"message":"Preparing the script","creditsCharged":0,"spendingCap":5384},"openInApp":false,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","links":{"app":"https://app.autoclips.app/studio-2?projectId=4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01","editor":"https://app.autoclips.app/editor/4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01"}},"approvedCredits":5384,"estimate":{"lower":3741,"upper":5384,"expected":5088}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"studio_autopilot_status","summary":"How the project's Autopilot film is going: stage, progress, credits spent, the limit, and what to do next.","description":"The project's latest Autopilot run as the website shows it: its status, stage and progress, credits spent and held, the spending limit, the pictures made so far, and what to do next in plain words (for example approve more with raise_cap when it waits at needs_cap). Checking also moves a run along when its next step is due. run is null when Autopilot never ran on this project.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"studio.autopilot.status","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_autopilot action=status","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio 2.0 project id (from studio projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio 2.0 project id (from studio projects list or create).","example":"4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"run":{"anyOf":[{"type":"object","properties":{"runId":{"type":"string"},"projectId":{"type":"string"},"status":{"description":"running, retrying, pausing, paused, needs_cap, needs_credits, needs_attention, completed, cancelled or taken_over.","type":"string","enum":["running","retrying","pausing","paused","needs_cap","needs_credits","needs_attention","completed","cancelled","taken_over"]},"statusWords":{"type":"string"},"stage":{"type":"string"},"stageLabel":{"type":"string"},"progress":{"type":"number","minimum":0,"maximum":100},"completedItems":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalItems":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"message":{"type":"string"},"creditsCharged":{"description":"Credits charged so far.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"creditsAuthorized":{"description":"Credits held for the step running now.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"spendingCapCredits":{"description":"The run's spending limit. Autopilot stops before a step that would go past the limit; one step's final cost can run a little over. It then waits at needs_cap.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ownLimit":{"description":"False when the run was started in the app: it has no spending limit of its own (spendingCapCredits shows 10,000,000) and your balance is its only limit. Set one with raise_cap.","type":"boolean"},"estimatedCredits":{"anyOf":[{"type":"object","properties":{"lower":{"description":"The least it is likely to cost.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"upper":{"description":"The top of the estimate for these settings; start asks you to approve this as the spending limit.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expected":{"description":"About what it usually costs.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["lower","upper","expected"],"additionalProperties":false},{"type":"null"}]},"settings":{"type":"object","properties":{"durationSeconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"storyMode":{"description":"How the story is told: mixed (the writer decides), narrated, dialogue or wordless. Set by the project.","type":"string"},"aspectRatio":{"type":"string"},"quality":{"type":"string"},"nativeAudio":{"type":"boolean"},"musicSource":{"type":"string"},"webSearch":{"type":"boolean"},"writerModel":{"type":"string"},"productionModel":{"type":"string"},"imageModel":{"type":"string"},"inSceneText":{"type":"boolean"},"textOnTop":{"type":"boolean"},"whoSpeaks":{"description":"Who says the words: auto (the writer decides), characters, narrator or none.","type":"string"},"speed":{"description":"How fast the finished video plays (1 = as rendered; voices keep their pitch, the soundtrack and outro stay at normal speed). Free.","type":"number"}},"required":["durationSeconds","storyMode","aspectRatio","quality","nativeAudio","musicSource","webSearch","writerModel","productionModel","imageModel","inSceneText","textOnTop","whoSpeaks","speed"],"additionalProperties":false},"outputs":{"type":"object","properties":{"characters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","url","createdAt"],"additionalProperties":false}},"assets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","url","createdAt"],"additionalProperties":false}},"characterSheets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","url","createdAt"],"additionalProperties":false}}},"required":["characters","assets","characterSheets"],"additionalProperties":false},"stale":{"description":"Set when the run looks stuck; retry it with control retry_stuck.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"retryCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"attention":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requiredCredits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["code","message","requiredCredits"],"additionalProperties":false},{"type":"null"}]},"pauseRequested":{"type":"boolean"},"nextStep":{"description":"What happens next, or what you need to do, in plain words.","type":"string"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["runId","projectId","status","statusWords","stage","stageLabel","progress","completedItems","totalItems","message","creditsCharged","creditsAuthorized","spendingCapCredits","ownLimit","estimatedCredits","settings","outputs","stale","retryCount","attention","pauseRequested","nextStep","createdAt","updatedAt","completedAt"],"additionalProperties":false},{"type":"null"}]},"jobId":{"description":"The job that follows this run, when it was started through the API.","anyOf":[{"type":"string"},{"type":"null"}]},"project":{"description":"The project, in the same shape as reading it with studio projects get.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"studio"},"title":{"type":"string"},"status":{"type":"string"},"video":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":{}},{"type":"null"}]},"links":{"type":"object","properties":{"app":{"type":"string"},"editor":{"type":"string"}},"required":["app","editor"],"additionalProperties":false}},"required":["id","product","title","status","video","links"],"additionalProperties":{}},"nextStep":{"type":"string"}},"required":["run","jobId","project","nextStep"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"run":{"runId":"e3a1c2b4-5d6f-4a7b-8c9d-0e1f2a3b4c5d","projectId":"4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01","status":"running","statusWords":"working","stage":"final-clips","stageLabel":"Final clips","progress":82,"completedItems":1,"totalItems":2,"message":"Preparing the script","creditsCharged":1450,"creditsAuthorized":0,"spendingCapCredits":5384,"ownLimit":true,"estimatedCredits":{"lower":3741,"upper":5384,"expected":5088},"settings":{"durationSeconds":30,"storyMode":"mixed","aspectRatio":"9:16","quality":"1080p","nativeAudio":true,"musicSource":"studio","webSearch":false,"writerModel":"trendScout","productionModel":"trendScout","imageModel":"dream5","inSceneText":true,"textOnTop":true,"whoSpeaks":"auto","speed":1.1},"outputs":{"characters":[],"assets":[],"characterSheets":[]},"stale":{"code":"stalled_action","message":"No worker is handling this overdue action. Retry from the last safe checkpoint."},"retryCount":0,"attention":null,"pauseRequested":false,"nextStep":"Autopilot looks stuck on this step. Retry it with control retry_stuck.","createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","completedAt":null},"jobId":"job_0199a2b3c4d5e6f708192a3b","project":{"id":"4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01","product":"studio","title":"The Moon Cat","status":"draft","mode":"autopilot","step":null,"durationSeconds":30,"settings":{"writerModel":null,"webSearch":false,"aspectRatio":"9:16","quality":"1080p","nativeAudio":true,"imageModel":null,"productionModel":null,"inSceneText":true,"textOnTop":true,"whoSpeaks":"auto","musicSource":"studio","enhanceBrief":true,"speed":1.1},"idea":"A cat who builds a rocket to reach the moon","counts":{"scenes":0,"characters":0,"assets":0,"clips":0,"clipsReady":0,"finalVideos":0},"video":null,"autopilot":{"runId":"e3a1c2b4-5d6f-4a7b-8c9d-0e1f2a3b4c5d","status":"running","stage":"script","progress":0,"message":"Preparing the script","creditsCharged":0,"spendingCap":5384},"openInApp":false,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","links":{"app":"https://app.autoclips.app/studio-2?projectId=4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01","editor":"https://app.autoclips.app/editor/4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01"}},"nextStep":"Autopilot looks stuck on this step. Retry it with control retry_stuck."}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/autopilot/control":{"post":{"operationId":"studio_autopilot_control","summary":"Pause, resume, retry a stuck step, hand the project back to the app, or cancel Autopilot. Free; asks first.","description":"Steers the project's Autopilot run. pause stops it after the step it is on (nothing is lost). resume goes on from the last finished step after a pause, a problem or adding credits (a run waiting at needs_cap needs raise_cap instead). retry_stuck retries a step no worker picked up. take_over stops Autopilot and hands the project back to Director mode in the app. cancel stops it for good. Credits already spent are never refunded, and what was made stays in the project. resume and retry_stuck spend credits again, so they also need the spend permission, and a run started in the app (which has no spending limit of its own) needs one set with raise_cap first. Free. Over MCP it shows what will happen and asks first.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.autopilot.control","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_autopilot action=control","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"command":{"description":"pause, resume, retry_stuck, take_over (back to Director mode in the app) or cancel (stops for good). resume and retry_stuck need the spend permission.","type":"string","enum":["pause","resume","take_over","cancel","retry_stuck"]}},"required":["command"],"additionalProperties":false},"example":{"command":"pause"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio 2.0 project id (from studio projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio 2.0 project id (from studio projects list or create).","example":"4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"run":{"type":"object","properties":{"runId":{"type":"string"},"projectId":{"type":"string"},"status":{"description":"running, retrying, pausing, paused, needs_cap, needs_credits, needs_attention, completed, cancelled or taken_over.","type":"string","enum":["running","retrying","pausing","paused","needs_cap","needs_credits","needs_attention","completed","cancelled","taken_over"]},"statusWords":{"type":"string"},"stage":{"type":"string"},"stageLabel":{"type":"string"},"progress":{"type":"number","minimum":0,"maximum":100},"completedItems":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalItems":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"message":{"type":"string"},"creditsCharged":{"description":"Credits charged so far.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"creditsAuthorized":{"description":"Credits held for the step running now.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"spendingCapCredits":{"description":"The run's spending limit. Autopilot stops before a step that would go past the limit; one step's final cost can run a little over. It then waits at needs_cap.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ownLimit":{"description":"False when the run was started in the app: it has no spending limit of its own (spendingCapCredits shows 10,000,000) and your balance is its only limit. Set one with raise_cap.","type":"boolean"},"estimatedCredits":{"anyOf":[{"type":"object","properties":{"lower":{"description":"The least it is likely to cost.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"upper":{"description":"The top of the estimate for these settings; start asks you to approve this as the spending limit.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expected":{"description":"About what it usually costs.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["lower","upper","expected"],"additionalProperties":false},{"type":"null"}]},"settings":{"type":"object","properties":{"durationSeconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"storyMode":{"description":"How the story is told: mixed (the writer decides), narrated, dialogue or wordless. Set by the project.","type":"string"},"aspectRatio":{"type":"string"},"quality":{"type":"string"},"nativeAudio":{"type":"boolean"},"musicSource":{"type":"string"},"webSearch":{"type":"boolean"},"writerModel":{"type":"string"},"productionModel":{"type":"string"},"imageModel":{"type":"string"},"inSceneText":{"type":"boolean"},"textOnTop":{"type":"boolean"},"whoSpeaks":{"description":"Who says the words: auto (the writer decides), characters, narrator or none.","type":"string"},"speed":{"description":"How fast the finished video plays (1 = as rendered; voices keep their pitch, the soundtrack and outro stay at normal speed). Free.","type":"number"}},"required":["durationSeconds","storyMode","aspectRatio","quality","nativeAudio","musicSource","webSearch","writerModel","productionModel","imageModel","inSceneText","textOnTop","whoSpeaks","speed"],"additionalProperties":false},"outputs":{"type":"object","properties":{"characters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","url","createdAt"],"additionalProperties":false}},"assets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","url","createdAt"],"additionalProperties":false}},"characterSheets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","url","createdAt"],"additionalProperties":false}}},"required":["characters","assets","characterSheets"],"additionalProperties":false},"stale":{"description":"Set when the run looks stuck; retry it with control retry_stuck.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"retryCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"attention":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requiredCredits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["code","message","requiredCredits"],"additionalProperties":false},{"type":"null"}]},"pauseRequested":{"type":"boolean"},"nextStep":{"description":"What happens next, or what you need to do, in plain words.","type":"string"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["runId","projectId","status","statusWords","stage","stageLabel","progress","completedItems","totalItems","message","creditsCharged","creditsAuthorized","spendingCapCredits","ownLimit","estimatedCredits","settings","outputs","stale","retryCount","attention","pauseRequested","nextStep","createdAt","updatedAt","completedAt"],"additionalProperties":false},"project":{"description":"The project, in the same shape as reading it with studio projects get.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"studio"},"title":{"type":"string"},"status":{"type":"string"},"video":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":{}},{"type":"null"}]},"links":{"type":"object","properties":{"app":{"type":"string"},"editor":{"type":"string"}},"required":["app","editor"],"additionalProperties":false}},"required":["id","product","title","status","video","links"],"additionalProperties":{}},"done":{"description":"What happened, in plain words.","type":"string"}},"required":["run","project","done"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"run":{"runId":"e3a1c2b4-5d6f-4a7b-8c9d-0e1f2a3b4c5d","projectId":"4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01","status":"pausing","statusWords":"stopping after the step it is on","stage":"script","stageLabel":"Script analysis","progress":0,"completedItems":0,"totalItems":1,"message":"Pausing after the current action","creditsCharged":0,"creditsAuthorized":0,"spendingCapCredits":5384,"ownLimit":true,"estimatedCredits":{"lower":3741,"upper":5384,"expected":5088},"settings":{"durationSeconds":30,"storyMode":"mixed","aspectRatio":"9:16","quality":"1080p","nativeAudio":true,"musicSource":"studio","webSearch":false,"writerModel":"trendScout","productionModel":"trendScout","imageModel":"dream5","inSceneText":true,"textOnTop":true,"whoSpeaks":"auto","speed":1.1},"outputs":{"characters":[],"assets":[],"characterSheets":[]},"stale":{"code":"stalled_action","message":"No worker is handling this overdue action. Retry from the last safe checkpoint."},"retryCount":0,"attention":null,"pauseRequested":true,"nextStep":"Autopilot stops after the step it is on. Check again with status in a minute.","createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","completedAt":null},"project":{"id":"4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01","product":"studio","title":"The Moon Cat","status":"draft","mode":"autopilot","step":null,"durationSeconds":30,"settings":{"writerModel":null,"webSearch":false,"aspectRatio":"9:16","quality":"1080p","nativeAudio":true,"imageModel":null,"productionModel":null,"inSceneText":true,"textOnTop":true,"whoSpeaks":"auto","musicSource":"studio","enhanceBrief":true,"speed":1.1},"idea":"A cat who builds a rocket to reach the moon","counts":{"scenes":0,"characters":0,"assets":0,"clips":0,"clipsReady":0,"finalVideos":0},"video":null,"autopilot":{"runId":"e3a1c2b4-5d6f-4a7b-8c9d-0e1f2a3b4c5d","status":"running","stage":"script","progress":0,"message":"Preparing the script","creditsCharged":0,"spendingCap":5384},"openInApp":false,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","links":{"app":"https://app.autoclips.app/studio-2?projectId=4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01","editor":"https://app.autoclips.app/editor/4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01"}},"done":"Autopilot will pause after the step it is on."}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/autopilot/quote":{"post":{"operationId":"studio_autopilot_quote","summary":"What an Autopilot film would cost with these settings: an estimate (its range), the steps, and your balance. Free.","description":"Estimates a whole Autopilot film for this project without starting anything: the likely range (lower to upper), what each step costs, and your balance. The cost depends on the length, the writer and planning AI, the picture maker, web search and the soundtrack, and on the project's cast once it has a script. Settings you leave out keep the project's saved Autopilot choices; the answer shows every setting the estimate is for. start asks you to approve the top of the estimate as the film's spending limit. It also says whether the project can start now, and if not, why (for example it is open in the app, or other work is running on it).\n\n**Permissions:** read.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"studio.autopilot.quote","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_autopilot action=quote","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"description":"How Autopilot makes the film. Every field is optional: one you leave out keeps the choice saved on the project for Autopilot (what the app's Autopilot panel shows), else the app's default; the length is the project's. quote answers the settings it will use. See studio options for every choice.","type":"object","properties":{"durationSeconds":{"description":"Length: How many seconds of story are written and rendered as clips. The finished film lasts that divided by its speed: a new film plays at 1.1x, so 30 seconds of clips make a film of about 27 seconds; pick speed 1 for the full length. Clips are the main cost, and they scale with length (the speed does not change the price).\nChoices:\n- 20 — 20 seconds: 20 seconds of clips: a film of about 18 seconds at the 1.1x speed a new film plays at, 20 seconds at 1x.\n- 30 — 30 seconds: 30 seconds of clips: a film of about 27 seconds at the 1.1x speed a new film plays at, 30 seconds at 1x.\n- 40 — 40 seconds: 40 seconds of clips: a film of about 36 seconds at the 1.1x speed a new film plays at, 40 seconds at 1x.\n- 50 — 50 seconds: 50 seconds of clips: a film of about 45 seconds at the 1.1x speed a new film plays at, 50 seconds at 1x.\n- 60 — 60 seconds: 60 seconds of clips: a film of about 55 seconds at the 1.1x speed a new film plays at, 60 seconds at 1x.\n- 70 — 70 seconds: 70 seconds of clips: a film of about 64 seconds at the 1.1x speed a new film plays at, 70 seconds at 1x.\n- 80 — 80 seconds: 80 seconds of clips: a film of about 73 seconds at the 1.1x speed a new film plays at, 80 seconds at 1x.\n- 90 — 90 seconds: 90 seconds of clips: a film of about 82 seconds at the 1.1x speed a new film plays at, 90 seconds at 1x.\nDefault: the project's length, else 30 (leave it out).\nSend it as text (\"30\") or a number (30).","anyOf":[{"description":"Length: How many seconds of story are written and rendered as clips. The finished film lasts that divided by its speed: a new film plays at 1.1x, so 30 seconds of clips make a film of about 27 seconds; pick speed 1 for the full length. Clips are the main cost, and they scale with length (the speed does not change the price).\nChoices:\n- 20 — 20 seconds: 20 seconds of clips: a film of about 18 seconds at the 1.1x speed a new film plays at, 20 seconds at 1x.\n- 30 — 30 seconds: 30 seconds of clips: a film of about 27 seconds at the 1.1x speed a new film plays at, 30 seconds at 1x.\n- 40 — 40 seconds: 40 seconds of clips: a film of about 36 seconds at the 1.1x speed a new film plays at, 40 seconds at 1x.\n- 50 — 50 seconds: 50 seconds of clips: a film of about 45 seconds at the 1.1x speed a new film plays at, 50 seconds at 1x.\n- 60 — 60 seconds: 60 seconds of clips: a film of about 55 seconds at the 1.1x speed a new film plays at, 60 seconds at 1x.\n- 70 — 70 seconds: 70 seconds of clips: a film of about 64 seconds at the 1.1x speed a new film plays at, 70 seconds at 1x.\n- 80 — 80 seconds: 80 seconds of clips: a film of about 73 seconds at the 1.1x speed a new film plays at, 80 seconds at 1x.\n- 90 — 90 seconds: 90 seconds of clips: a film of about 82 seconds at the 1.1x speed a new film plays at, 90 seconds at 1x.\nDefault: the project's length, else 30 (leave it out).","type":"string","enum":["20","30","40","50","60","70","80","90"]},{"type":"number","enum":[20,30,40,50,60,70,80,90]}]},"aspectRatio":{"description":"Frame: The shape of the film.\nChoices:\n- 9:16 — 9:16: Tall, for TikTok, Reels and Shorts.\n- 16:9 — 16:9: Wide, for YouTube.\n- 1:1 — 1:1: Square.\n- 4:3 — 4:3: Classic TV shape.\n- 3:4 — 3:4: Portrait photo shape.\nDefault: the frame saved in the project's Autopilot panel, else 9:16 (leave it out).","type":"string","enum":["9:16","16:9","1:1","4:3","3:4"]},"quality":{"description":"Quality: Clips render at 720p. \"1080p\" adds a free AI upscale at the same price.\nChoices:\n- 1080p — 1080p: Rendered at 720p, then upscaled to 1080p for free.\n- 720p — 720p: Rendered and delivered at 720p.\nDefault: the quality saved in the project's Autopilot panel, else 1080p (leave it out).","type":"string","enum":["1080p","720p"]},"nativeAudio":{"description":"The video model speaks the lines and adds sound. Always on when characters talk. Default: the choice saved in the project's Autopilot panel, else on (leave it out).","type":"boolean"},"musicSource":{"description":"Soundtrack: Where the music comes from.\nChoices:\n- studio — Studio soundtrack: An AI soundtrack written for the story. (36 credits per soundtrack take)\n- native — Scored inside the clip: The video model scores the clip itself. Only for a single clip of 30 seconds or less with native audio on.\nDefault: the soundtrack saved in the project's Autopilot panel, else studio (leave it out).","type":"string","enum":["studio","native"]},"webSearch":{"description":"Let the writer read the web for facts and trends. Adds a few credits per request. Default: the choice saved in the project's Autopilot panel, else off (leave it out).","type":"boolean"},"writerModel":{"description":"Writer: Which AI writes the brief and the script. Billed at the real AI cost after each request. Every writer is offered on every plan; a new project starts on the app's pick for your plan.\nChoices:\n- opus55 — Claude Opus 5.5: Strongest physical logic and continuity for demanding stories. A 30-second script costs about 210 credits, a longer one more (billed at the real AI cost).\n- trendScout — Kimi K3: Strong, timely, research-led story development. A 30-second script costs about 158 credits, a longer one more (billed at the real AI cost).\n- quickSpark — Gemini 3.8 Flash: Fast brainstorming with clear visual beats. A 30-second script costs about 36 credits, a longer one more (billed at the real AI cost).\nDefault: the writer saved in the project's Autopilot panel, else the project's writer, else Kimi K3 (leave it out).","type":"string","enum":["opus55","trendScout","quickSpark"]},"productionModel":{"description":"Planning AI: Which AI plans the pictures, character sheets and clips from the script (it looks at the pictures, so only vision-capable writers). A new project starts on the app's pick for your plan.\nChoices:\n- opus55 — Claude Opus 5.5: Strongest physical logic and continuity for demanding stories. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 783 credits, a longer film or a bigger cast more (billed at the real AI cost).\n- trendScout — Kimi K3: Strong, timely, research-led story development. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 589 credits, a longer film or a bigger cast more (billed at the real AI cost).\n- quickSpark — Gemini 3.8 Flash: Fast brainstorming with clear visual beats. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 150 credits, a longer film or a bigger cast more (billed at the real AI cost).\nDefault: the planning AI saved in the project's Autopilot panel, else Kimi K3 (leave it out).","type":"string","enum":["opus55","trendScout","quickSpark"]},"imageModel":{"description":"Picture maker: Which model draws the characters, places, objects and character sheets.\nChoices:\n- dream5 — Dream 5: Recommended for polished 3D character and asset references. (41 credits per picture)\n- gptImage2High — ChatGPT Image 2.0 High: Strong prompt accuracy and crisp production detail. (30 credits per picture)\n- nanoBanana2 — Nano Banana 2: Fast high-quality generations with flexible references. (72 credits per picture)\nDefault: the picture maker saved in the project's Autopilot panel, else dream5 (leave it out).","type":"string","enum":["dream5","gptImage2High","nanoBanana2"]},"inSceneText":{"description":"Signs, screens and labels the video model draws inside the picture. Default: the choice saved in the project's Autopilot panel, else on (leave it out).","type":"boolean"},"textOnTop":{"description":"Titles, chat messages, labels and an end card drawn over the finished video (free, editable afterwards). Default: the choice saved in the project's Autopilot panel, else on (leave it out).","type":"boolean"},"whoSpeaks":{"description":"Who speaks: Who says the words: the writer decides (auto), only the characters, only a narrator, or nobody. A fixed choice is guaranteed; it shapes the brief and the script.\nChoices:\n- auto — Auto: A narrator, the characters, or both. The writer picks whatever keeps people watching.\n- characters — Only the characters: No narrator. Every word is said on screen by a character.\n- narrator — Only a narrator: A voice-over tells the story. The characters never speak.\n- none — No one: No talking at all. The story is told with action, sound and music.\nDefault: the who speaks saved in the project's Autopilot panel, else auto (leave it out).","type":"string","enum":["auto","characters","narrator","none"]},"speed":{"description":"Final video speed: How fast the finished video plays. Every clip plays faster with its voices at their own pitch; the soundtrack and the outro stay at normal speed. A finished video lasts its clips' seconds divided by the speed. Free: clips are priced by the seconds rendered, which the speed does not change. A film joined before speeds existed stays at 1x until a speed is chosen.\nChoices:\n- 1 — 1x: Normal speed, as the clips were rendered. (Free)\n- 1.1 — 1.1x: A little quicker than rendered. What a new film plays at. (Free)\n- 1.25 — 1.25x: Recommended: the quick pace short-form edits use. (Free)\n- 1.5 — 1.5x: 1.5 times as fast as rendered. (Free)\n- 2 — 2x: 2 times as fast as rendered. (Free)\nDefault: the speed saved in the project's Autopilot panel, else 1.1x (leave it out).\nSend the value as text (\"1.25\") or a number (1.25).\nAutopilot joins the film at this speed and saves it on the film, in place of the speed the film had.","anyOf":[{"description":"Final video speed: How fast the finished video plays. Every clip plays faster with its voices at their own pitch; the soundtrack and the outro stay at normal speed. A finished video lasts its clips' seconds divided by the speed. Free: clips are priced by the seconds rendered, which the speed does not change. A film joined before speeds existed stays at 1x until a speed is chosen.\nChoices:\n- 1 — 1x: Normal speed, as the clips were rendered. (Free)\n- 1.1 — 1.1x: A little quicker than rendered. What a new film plays at. (Free)\n- 1.25 — 1.25x: Recommended: the quick pace short-form edits use. (Free)\n- 1.5 — 1.5x: 1.5 times as fast as rendered. (Free)\n- 2 — 2x: 2 times as fast as rendered. (Free)\nDefault: the speed saved in the project's Autopilot panel, else 1.1x (leave it out).","type":"string","enum":["1","2","1.1","1.25","1.5"]},{"type":"number","enum":[1,1.1,1.25,1.5,2]}]}},"additionalProperties":false}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio 2.0 project id (from studio projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio 2.0 project id (from studio projects list or create).","example":"4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"settings":{"description":"The settings the estimate is for, with every default filled in.","type":"object","properties":{"durationSeconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"storyMode":{"description":"How the story is told: mixed (the writer decides), narrated, dialogue or wordless. Set by the project.","type":"string"},"aspectRatio":{"type":"string"},"quality":{"type":"string"},"nativeAudio":{"type":"boolean"},"musicSource":{"type":"string"},"webSearch":{"type":"boolean"},"writerModel":{"type":"string"},"productionModel":{"type":"string"},"imageModel":{"type":"string"},"inSceneText":{"type":"boolean"},"textOnTop":{"type":"boolean"},"whoSpeaks":{"description":"Who says the words: auto (the writer decides), characters, narrator or none.","type":"string"},"speed":{"description":"How fast the finished video plays (1 = as rendered; voices keep their pitch, the soundtrack and outro stay at normal speed). Free.","type":"number"}},"required":["durationSeconds","storyMode","aspectRatio","quality","nativeAudio","musicSource","webSearch","writerModel","productionModel","imageModel","inSceneText","textOnTop","whoSpeaks","speed"],"additionalProperties":false},"estimate":{"type":"object","properties":{"lower":{"description":"The least it is likely to cost.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"upper":{"description":"The top of the estimate for these settings; start asks you to approve this as the spending limit.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expected":{"description":"About what it usually costs.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["lower","upper","expected"],"additionalProperties":false},"breakdown":{"description":"The expected cost per step, plus the margin up to the top of the estimate.","type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["label","credits"],"additionalProperties":false}},"inventory":{"type":"object","properties":{"characters":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"assets":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clips":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["characters","assets","clips"],"additionalProperties":false},"pricedFrom":{"description":"script: priced from the project's saved script and cast. typical: no script yet, so a typical cast for this length.","type":"string","enum":["script","typical"]},"balance":{"anyOf":[{"type":"number"},{"type":"null"}]},"affordable":{"description":"True when your balance covers the top of the estimate (the spending limit start asks you to approve).","anyOf":[{"type":"boolean"},{"type":"null"}]},"readyToStart":{"type":"boolean"},"blocker":{"description":"Why it cannot start right now, in plain words, or null.","anyOf":[{"type":"string"},{"type":"null"}]},"message":{"type":"string"}},"required":["projectId","settings","estimate","breakdown","inventory","pricedFrom","balance","affordable","readyToStart","blocker","message"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"projectId":"4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01","settings":{"durationSeconds":30,"storyMode":"mixed","aspectRatio":"9:16","quality":"1080p","nativeAudio":true,"musicSource":"studio","webSearch":false,"writerModel":"trendScout","productionModel":"trendScout","imageModel":"dream5","inSceneText":true,"textOnTop":true,"whoSpeaks":"auto","speed":1.1},"estimate":{"lower":3741,"upper":5384,"expected":5088},"breakdown":[{"label":"Writing the script (billed at the real AI cost)","credits":158},{"label":"Planning the character and place pictures (billed at the real AI cost)","credits":144},{"label":"Character and place pictures","credits":369},{"label":"Planning the character sheets (billed at the real AI cost)","credits":70},{"label":"Planning the clips (billed at the real AI cost)","credits":375},{"label":"Video clips","credits":3936},{"label":"Soundtrack","credits":36},{"label":"Safety margin (up to the top of the estimate)","credits":296}],"inventory":{"characters":2,"assets":5,"clips":2},"pricedFrom":"typical","balance":20000,"affordable":true,"readyToStart":true,"blocker":null,"message":"About 5,088 credits, between 3,741 and 5,384. start asks you to approve 5,384 as the film's spending limit; each step is charged as it happens, so it usually costs less. Autopilot stops before a step that would go past the limit; one step's final cost can run a little over. The film: 30 seconds of clips, a film of about 27 seconds at 1.1x (speed 1 keeps all 30)."}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/autopilot/raise-cap":{"post":{"operationId":"studio_autopilot_raise_cap","summary":"Approve more credits for an Autopilot film, or set a limit on one started in the app. Paid: you approve a spending limit on the extra.","description":"Sets the spending limit of the project's Autopilot run to newCapCredits. What you approve is a spending limit on the extra, never a charge. On a run with a limit, the new one must be higher and the extra is the difference. A run started in the app has no limit of its own (your balance is its only limit): this sets one, and the extra is what the new limit lets it spend from now (the limit minus what is already spent or held; held credits count as spent, so if the step holding them costs less, the rest stays within the new limit). While the film works those numbers move, so the amount first asked is kept (until 10 minutes after the last ask, 30 minutes at most) and the yes is not asked again; if the film spent or held more since, it may spend less from now than you approved. A run waiting at needs_cap goes on at once; the status answer says the least limit it needs (attention.requiredCredits). Nothing is charged now: Autopilot charges each step as it happens. Autopilot stops before a step that would go past the limit; one step's final cost can run a little over.\n\n**Permissions:** edit, spend.\n**Cost:** You approve how much the spending limit may grow: only the extra, not what the whole run costs, and not a price. The work is charged step by step as it runs, usually less. Autopilot stops before a step that would go past its raised limit, but one step's final cost can run a little over. Send `max_credits` (the most you accept to add to the spending limit) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the amount and a quote_token.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"studio.autopilot.raise_cap","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"studio_autopilot action=raise_cap","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"newCapCredits":{"description":"The new spending limit for the whole film, in credits (not the extra amount), at most 9,999,999. It must cover what is already spent or held, and be higher than today's limit when the run has one; status shows both.","type":"integer","minimum":1,"maximum":9999999},"max_credits":{"type":"integer","minimum":0,"description":"The most you accept to add to the spending limit. If more would be added, nothing runs and you get 402 with the amount. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to add exactly that amount to the spending limit. Works once, for 10 minutes."}},"required":["newCapCredits"],"additionalProperties":false},"example":{"newCapCredits":7000}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio 2.0 project id (from studio projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio 2.0 project id (from studio projects list or create).","example":"4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"run":{"type":"object","properties":{"runId":{"type":"string"},"projectId":{"type":"string"},"status":{"description":"running, retrying, pausing, paused, needs_cap, needs_credits, needs_attention, completed, cancelled or taken_over.","type":"string","enum":["running","retrying","pausing","paused","needs_cap","needs_credits","needs_attention","completed","cancelled","taken_over"]},"statusWords":{"type":"string"},"stage":{"type":"string"},"stageLabel":{"type":"string"},"progress":{"type":"number","minimum":0,"maximum":100},"completedItems":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalItems":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"message":{"type":"string"},"creditsCharged":{"description":"Credits charged so far.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"creditsAuthorized":{"description":"Credits held for the step running now.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"spendingCapCredits":{"description":"The run's spending limit. Autopilot stops before a step that would go past the limit; one step's final cost can run a little over. It then waits at needs_cap.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ownLimit":{"description":"False when the run was started in the app: it has no spending limit of its own (spendingCapCredits shows 10,000,000) and your balance is its only limit. Set one with raise_cap.","type":"boolean"},"estimatedCredits":{"anyOf":[{"type":"object","properties":{"lower":{"description":"The least it is likely to cost.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"upper":{"description":"The top of the estimate for these settings; start asks you to approve this as the spending limit.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expected":{"description":"About what it usually costs.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["lower","upper","expected"],"additionalProperties":false},{"type":"null"}]},"settings":{"type":"object","properties":{"durationSeconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"storyMode":{"description":"How the story is told: mixed (the writer decides), narrated, dialogue or wordless. Set by the project.","type":"string"},"aspectRatio":{"type":"string"},"quality":{"type":"string"},"nativeAudio":{"type":"boolean"},"musicSource":{"type":"string"},"webSearch":{"type":"boolean"},"writerModel":{"type":"string"},"productionModel":{"type":"string"},"imageModel":{"type":"string"},"inSceneText":{"type":"boolean"},"textOnTop":{"type":"boolean"},"whoSpeaks":{"description":"Who says the words: auto (the writer decides), characters, narrator or none.","type":"string"},"speed":{"description":"How fast the finished video plays (1 = as rendered; voices keep their pitch, the soundtrack and outro stay at normal speed). Free.","type":"number"}},"required":["durationSeconds","storyMode","aspectRatio","quality","nativeAudio","musicSource","webSearch","writerModel","productionModel","imageModel","inSceneText","textOnTop","whoSpeaks","speed"],"additionalProperties":false},"outputs":{"type":"object","properties":{"characters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","url","createdAt"],"additionalProperties":false}},"assets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","url","createdAt"],"additionalProperties":false}},"characterSheets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","url","createdAt"],"additionalProperties":false}}},"required":["characters","assets","characterSheets"],"additionalProperties":false},"stale":{"description":"Set when the run looks stuck; retry it with control retry_stuck.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"retryCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"attention":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requiredCredits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["code","message","requiredCredits"],"additionalProperties":false},{"type":"null"}]},"pauseRequested":{"type":"boolean"},"nextStep":{"description":"What happens next, or what you need to do, in plain words.","type":"string"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["runId","projectId","status","statusWords","stage","stageLabel","progress","completedItems","totalItems","message","creditsCharged","creditsAuthorized","spendingCapCredits","ownLimit","estimatedCredits","settings","outputs","stale","retryCount","attention","pauseRequested","nextStep","createdAt","updatedAt","completedAt"],"additionalProperties":false},"project":{"description":"The project, in the same shape as reading it with studio projects get.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"studio"},"title":{"type":"string"},"status":{"type":"string"},"video":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":{}},{"type":"null"}]},"links":{"type":"object","properties":{"app":{"type":"string"},"editor":{"type":"string"}},"required":["app","editor"],"additionalProperties":false}},"required":["id","product","title","status","video","links"],"additionalProperties":{}},"previousCapCredits":{"description":"The limit before; null when the run had no limit of its own (it was started in the app).","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"newCapCredits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"extraApprovedCredits":{"description":"The extra this approved: how much more the film may spend than under its old limit (or, on a run that had no limit, from now). Never more than you approved; less when the film spent or held more since the ask.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"resumed":{"description":"True when the film was waiting for this and goes on now.","type":"boolean"}},"required":["run","project","previousCapCredits","newCapCredits","extraApprovedCredits","resumed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"run":{"runId":"e3a1c2b4-5d6f-4a7b-8c9d-0e1f2a3b4c5d","projectId":"4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01","status":"running","statusWords":"working","stage":"final-clips","stageLabel":"Final clips","progress":80,"completedItems":0,"totalItems":1,"message":"Continuing from the spending-cap checkpoint","creditsCharged":4984,"creditsAuthorized":0,"spendingCapCredits":7000,"ownLimit":true,"estimatedCredits":{"lower":3741,"upper":5384,"expected":5088},"settings":{"durationSeconds":30,"storyMode":"mixed","aspectRatio":"9:16","quality":"1080p","nativeAudio":true,"musicSource":"studio","webSearch":false,"writerModel":"trendScout","productionModel":"trendScout","imageModel":"dream5","inSceneText":true,"textOnTop":true,"whoSpeaks":"auto","speed":1.1},"outputs":{"characters":[],"assets":[],"characterSheets":[]},"stale":{"code":"stalled_action","message":"No worker is handling this overdue action. Retry from the last safe checkpoint."},"retryCount":0,"attention":null,"pauseRequested":false,"nextStep":"Autopilot looks stuck on this step. Retry it with control retry_stuck.","createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","completedAt":null},"project":{"id":"4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01","product":"studio","title":"The Moon Cat","status":"draft","mode":"autopilot","step":null,"durationSeconds":30,"settings":{"writerModel":null,"webSearch":false,"aspectRatio":"9:16","quality":"1080p","nativeAudio":true,"imageModel":null,"productionModel":null,"inSceneText":true,"textOnTop":true,"whoSpeaks":"auto","musicSource":"studio","enhanceBrief":true,"speed":1.1},"idea":"A cat who builds a rocket to reach the moon","counts":{"scenes":0,"characters":0,"assets":0,"clips":0,"clipsReady":0,"finalVideos":0},"video":null,"autopilot":{"runId":"e3a1c2b4-5d6f-4a7b-8c9d-0e1f2a3b4c5d","status":"running","stage":"script","progress":0,"message":"Preparing the script","creditsCharged":0,"spendingCap":5384},"openInApp":false,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","links":{"app":"https://app.autoclips.app/studio-2?projectId=4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01","editor":"https://app.autoclips.app/editor/4c1d7e2a-9b3f-4a10-8e55-2f6a7b8c9d01"}},"previousCapCredits":5384,"newCapCredits":7000,"extraApprovedCredits":1616,"resumed":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/brief":{"get":{"operationId":"studio_brief_get","summary":"A Studio project's production brief, and whether Autopilot will write the script from it.","description":"The brief saved on the project (written by write_brief or in the app), whether it still matches the project (current), and whether studio_autopilot start will write from it (usedByAutopilot).\n\n**Permissions:** read.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"studio.brief.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_ideas action=get_brief","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects list or create).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"brief":{"description":"The production brief (Markdown): the cast, a timed transcript of what is said, a beat-by-beat plan and notes. Null when the project has none.","anyOf":[{"type":"string"},{"type":"null"}]},"current":{"description":"True when the brief was written for the project as it is now (its idea, length, promotion and attachments).","type":"boolean"},"usedByAutopilot":{"description":"True when studio_autopilot start will write the script from this brief rather than the idea as typed.","type":"boolean"},"beats":{"description":"How many beats the brief plans, when just written.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"warnings":{"description":"Things to check in a brief just written (for example a beat with too many words).","type":"array","items":{"type":"string"}},"truncated":{"description":"True when the brief hit its length limit and ends early.","type":"boolean"},"note":{"type":"string"},"replaced":{"description":"True when a brief the project already had was replaced.","type":"boolean"}},"required":["projectId","brief","current","usedByAutopilot","beats","warnings","truncated","note"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"studio_brief_generate","summary":"Turn a Studio project's idea into a production brief and save it; Autopilot then writes the script from it. Free.","description":"A Studio writer turns the project's idea (with its length, who speaks, the product it promotes and how many pictures and files are attached) into a production brief: the cast, a timed transcript of what is said, a beat-by-beat plan and notes. It is saved on the project, and studio_autopilot start writes the script from it. Show it to the user; change it with revise_brief, or go back to the idea as typed with discard_brief. Free; counts toward the daily limit for free AI helpers. Only before the script is written, and not while the project is open and being edited in the app or while Studio works on it. It replaces a brief the project already has (in AI apps it asks first). An app tab that had the project open before this change keeps it when it saves. One exception: in an app tab opened after this change, a very first change that puts things back as they were (for example removing a promotion or a brief the API added) does not stick, and the API's version stays. To take it back, use remove_promotion or discard_brief here, or make any other change in that tab first and then remove it.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.brief.generate","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_ideas action=write_brief","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects list or create).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"brief":{"description":"The production brief (Markdown): the cast, a timed transcript of what is said, a beat-by-beat plan and notes. Null when the project has none.","anyOf":[{"type":"string"},{"type":"null"}]},"current":{"description":"True when the brief was written for the project as it is now (its idea, length, promotion and attachments).","type":"boolean"},"usedByAutopilot":{"description":"True when studio_autopilot start will write the script from this brief rather than the idea as typed.","type":"boolean"},"beats":{"description":"How many beats the brief plans, when just written.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"warnings":{"description":"Things to check in a brief just written (for example a beat with too many words).","type":"array","items":{"type":"string"}},"truncated":{"description":"True when the brief hit its length limit and ends early.","type":"boolean"},"note":{"type":"string"},"replaced":{"description":"True when a brief the project already had was replaced.","type":"boolean"}},"required":["projectId","brief","current","usedByAutopilot","beats","warnings","truncated","note"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"studio_brief_discard","summary":"Throw away a Studio project's brief, so the script is written from the idea as typed. Free.","description":"Removes the saved brief (the app's \"use the original\"): studio_autopilot start then writes from the idea as typed. This is the sure way to take back a brief the API wrote: in an app tab opened after it was written, clearing it as the very first change there does not stick. Only before the script is written, and not while the project is open and being edited in the app or while Studio works on it. In AI apps it asks first.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.brief.discard","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_ideas action=discard_brief","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects list or create).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"brief":{"description":"The production brief (Markdown): the cast, a timed transcript of what is said, a beat-by-beat plan and notes. Null when the project has none.","anyOf":[{"type":"string"},{"type":"null"}]},"current":{"description":"True when the brief was written for the project as it is now (its idea, length, promotion and attachments).","type":"boolean"},"usedByAutopilot":{"description":"True when studio_autopilot start will write the script from this brief rather than the idea as typed.","type":"boolean"},"beats":{"description":"How many beats the brief plans, when just written.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"warnings":{"description":"Things to check in a brief just written (for example a beat with too many words).","type":"array","items":{"type":"string"}},"truncated":{"description":"True when the brief hit its length limit and ends early.","type":"boolean"},"note":{"type":"string"},"replaced":{"description":"True when a brief the project already had was replaced.","type":"boolean"},"discarded":{"type":"boolean"}},"required":["projectId","brief","current","usedByAutopilot","beats","warnings","truncated","note","discarded"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/brief/revise":{"post":{"operationId":"studio_brief_revise","summary":"Change a Studio project's brief the way you describe, and save it. Free.","description":"The writer rewrites the saved brief with your change (\"make the cat the villain\", \"end on the product\") and saves it in its place. The brief must match the project as it is now; after the idea, length, promotion or attachments changed, write a new one with write_brief. Free; counts toward the daily limit for free AI helpers. Change request up to 3000 characters. Only before the script is written, and not while the project is open and being edited in the app or while Studio works on it. An app tab that had the project open before this change keeps it when it saves. One exception: in an app tab opened after this change, a very first change that puts things back as they were (for example removing a promotion or a brief the API added) does not stick, and the API's version stays. To take it back, use remove_promotion or discard_brief here, or make any other change in that tab first and then remove it.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.brief.revise","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_ideas action=revise_brief","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"changeRequest":{"description":"What should change, in plain words.","type":"string","minLength":2,"maxLength":3000}},"required":["changeRequest"],"additionalProperties":false},"example":{"changeRequest":"End on the robot and the star together in the sky, and make the last line funnier."}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects list or create).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"brief":{"description":"The production brief (Markdown): the cast, a timed transcript of what is said, a beat-by-beat plan and notes. Null when the project has none.","anyOf":[{"type":"string"},{"type":"null"}]},"current":{"description":"True when the brief was written for the project as it is now (its idea, length, promotion and attachments).","type":"boolean"},"usedByAutopilot":{"description":"True when studio_autopilot start will write the script from this brief rather than the idea as typed.","type":"boolean"},"beats":{"description":"How many beats the brief plans, when just written.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"warnings":{"description":"Things to check in a brief just written (for example a beat with too many words).","type":"array","items":{"type":"string"}},"truncated":{"description":"True when the brief hit its length limit and ends early.","type":"boolean"},"note":{"type":"string"},"replaced":{"description":"True when a brief the project already had was replaced.","type":"boolean"}},"required":["projectId","brief","current","usedByAutopilot","beats","warnings","truncated","note"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/characters/picture-check":{"post":{"operationId":"studio_pictures_check","summary":"Check the pictures on the character cards against what the script says each character looks like.","description":"An AI looks at the pictures on each character's card (references, or the character's own picture) and the script's words about that character, and says where they disagree, for example \"Your script says Ayoub has braids, but the picture on Ayoub's card shows curly hair.\" A character's own card picture always decides its looks; only lasting looks count (hair, beard, glasses, age, build, skin, gender), never clothes or style. When the script's words disagree, Studio rewrites the description to follow the picture straight away and reports it (pictureCheck state followed): tell the person, who can move a picture put on the wrong card. Only a disagreement the check could not describe stays open (state conflict): every paid step for that character (prepare_pictures, make_pictures, prepare_sheets, make_sheets, clip planning) is refused until resolve_picture, and Autopilot pauses with attention code picture_conflict. The app runs this by itself whenever a card changes. A card that has not changed since its last check is answered from the saved check without asking the AI again (force: true asks again). Free; counts toward the daily limit for free AI helpers.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.pictures.check","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_looks action=check_pictures","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"characterIds":{"description":"Only these characters. Default: every character with a picture on its card.","minItems":1,"maxItems":24,"type":"array","items":{"description":"The id of a character, object or place (from studio_looks overview).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_.:-]+$"}},"force":{"description":"true: check again even cards that were already checked as they are. Default false.","type":"boolean"}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"checked":{"description":"Cards the AI looked at in this call.","type":"number"},"conflicts":{"description":"Disagreements still waiting for the person's choice (resolve_picture).","type":"array","items":{"type":"object","properties":{"characterId":{"type":"string"},"characterName":{"type":"string"},"message":{"description":"The disagreement in plain words, as the app's card says it. Show it to the person.","type":"string"},"scriptSays":{"type":"string"},"pictureShows":{"type":"string"},"suggestedCharacterId":{"description":"Another character the picture fits, or \"\" when none clearly does.","type":"string"},"canUsePicture":{"type":"boolean"},"canMovePicture":{"type":"boolean"}},"required":["characterId","characterName","message","scriptSays","pictureShows","suggestedCharacterId","canUsePicture","canMovePicture"],"additionalProperties":{}}},"followed":{"description":"Characters whose description now follows the picture on their card because the script said otherwise. Tell the person.","type":"array","items":{"type":"object","properties":{"characterId":{"type":"string"},"characterName":{"type":"string"},"message":{"description":"The disagreement in plain words, as the app's card says it. Show it to the person.","type":"string"},"scriptSays":{"type":"string"},"pictureShows":{"type":"string"},"suggestedCharacterId":{"description":"Another character the picture fits, or \"\" when none clearly does.","type":"string"},"canUsePicture":{"type":"boolean"},"canMovePicture":{"type":"boolean"}},"required":["characterId","characterName","message","scriptSays","pictureShows","suggestedCharacterId","canUsePicture","canMovePicture"],"additionalProperties":{}}},"characters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["character","object","place"]},"name":{"type":"string"},"canHavePicture":{"description":"False for fixed furniture, which is drawn as part of its place.","type":"boolean"},"direction":{"description":"The picture direction make_pictures draws from: ready; missing (none yet); or outdated (written before Studio could see this item's reference pictures). A missing or outdated one is written by prepare_pictures before the item is drawn, as the app does; an item that already has its picture keeps its direction as it is until you name the item to draw it again.","type":"string","enum":["ready","missing","outdated"]},"picture":{"description":"The picture the film uses. source \"yours\": your own picture, used as it is: nothing is drawn for it. To draw it from that picture, name it in prepare_pictures first (the app's \"Draw from it\"), then in make_pictures.","anyOf":[{"type":"object","properties":{"url":{"type":"string"},"versionId":{"type":"string"},"source":{"type":"string","enum":["made","yours"]}},"required":["url","versionId","source"],"additionalProperties":{}},{"type":"null"}]},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"}},"required":["id","name","url"],"additionalProperties":{}}}},"required":["id","kind","name","canHavePicture","direction","picture","references"],"additionalProperties":{}}}},"required":["projectId","checked","conflicts","followed","characters"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/characters/{characterId}/picture-check":{"post":{"operationId":"studio_pictures_resolve","summary":"Answer a picture-vs-script disagreement on a character: keep, move the picture, or use the picture.","description":"The person's answer to a disagreement check_pictures found (the same buttons as the app's card). Ask the person; never choose for them. On a followed card (the description already follows the picture), keep means the person has seen it, and move_picture fixes a picture put on the wrong card. use_picture: the character's description is rewritten to follow the picture (clothes and story notes stay), and its picture and sheet directions are written again before the next drawing. move_picture: the card's reference pictures move to another character (moveTo, default the one the check suggested). When that character's own pictures were flagged as showing this one, the two cards swap. Both cards are checked again (check_pictures) before drawing. keep: nothing changes; the disagreement is accepted as it is. A character's own card picture always decides its looks; only lasting looks count (hair, beard, glasses, age, build, skin, gender), never clothes or style. When the script's words disagree, Studio rewrites the description to follow the picture straight away and reports it (pictureCheck state followed): tell the person, who can move a picture put on the wrong card. Only a disagreement the check could not describe stays open (state conflict): every paid step for that character (prepare_pictures, make_pictures, prepare_sheets, make_sheets, clip planning) is refused until resolve_picture, and Autopilot pauses with attention code picture_conflict. Free. Refused while the project is open and saving in the app, and while anything runs on it.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.pictures.resolve","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_looks action=resolve_picture","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"choice":{"description":"use_picture, move_picture or keep.","type":"string","enum":["use_picture","move_picture","keep"]},"moveTo":{"description":"Only with move_picture: the character the pictures go to. Default: the one the check suggested.","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_.:-]+$"}},"required":["choice"],"additionalProperties":false},"example":{"choice":"use_picture"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"characterId","in":"path","required":true,"schema":{"description":"The character whose card has the disagreement.","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_.:-]+$"},"description":"The character whose card has the disagreement.","example":"character_mia"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"choice":{"type":"string"},"characters":{"description":"The characters this changed, as they are now.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["character","object","place"]},"name":{"type":"string"},"canHavePicture":{"description":"False for fixed furniture, which is drawn as part of its place.","type":"boolean"},"direction":{"description":"The picture direction make_pictures draws from: ready; missing (none yet); or outdated (written before Studio could see this item's reference pictures). A missing or outdated one is written by prepare_pictures before the item is drawn, as the app does; an item that already has its picture keeps its direction as it is until you name the item to draw it again.","type":"string","enum":["ready","missing","outdated"]},"picture":{"description":"The picture the film uses. source \"yours\": your own picture, used as it is: nothing is drawn for it. To draw it from that picture, name it in prepare_pictures first (the app's \"Draw from it\"), then in make_pictures.","anyOf":[{"type":"object","properties":{"url":{"type":"string"},"versionId":{"type":"string"},"source":{"type":"string","enum":["made","yours"]}},"required":["url","versionId","source"],"additionalProperties":{}},{"type":"null"}]},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"}},"required":["id","name","url"],"additionalProperties":{}}}},"required":["id","kind","name","canHavePicture","direction","picture","references"],"additionalProperties":{}}},"conflicts":{"description":"Disagreements still waiting for a choice.","type":"array","items":{"type":"object","properties":{"characterId":{"type":"string"},"characterName":{"type":"string"},"message":{"description":"The disagreement in plain words, as the app's card says it. Show it to the person.","type":"string"},"scriptSays":{"type":"string"},"pictureShows":{"type":"string"},"suggestedCharacterId":{"description":"Another character the picture fits, or \"\" when none clearly does.","type":"string"},"canUsePicture":{"type":"boolean"},"canMovePicture":{"type":"boolean"}},"required":["characterId","characterName","message","scriptSays","pictureShows","suggestedCharacterId","canUsePicture","canMovePicture"],"additionalProperties":{}}},"note":{"type":"string"}},"required":["projectId","choice","characters","conflicts","note"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/characters/{characterId}/voice":{"put":{"operationId":"studio_characters_set_voice","summary":"Give a speaking character a voice from a recording (your media library or your own cloned voice), or remove it.","description":"The clips make a character speak with the voice of a short recording: send mediaId (a sound in your media library, autoclips_media) or voiceId (one of your own cloned voices, by id or name, from autoclips_voices list), or remove: true. A film takes up to 3 character voices, 30 seconds together; one recording can be 30 seconds at most (use a short, clean recording of one person speaking). It is turned into the MP3 the clips use and stored in Studio. Free; counts toward the daily limit for uploads. A new or removed voice clears planned clips (the app does the same): send clearPlannedClips: true then; an AI app asks first. Not for wordless films. Refused while the project is open and saving in the app, and while anything runs on it.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.characters.set_voice","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_looks action=set_voice","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mediaId":{"description":"A sound recording in your media library: one person speaking, up to 30 seconds.","type":"string","pattern":"^[a-fA-F0-9]{24}$"},"voiceId":{"description":"One of your own cloned voices (its id or exact name, from autoclips_voices list). Its original recording is used.","type":"string","minLength":1,"maxLength":128},"remove":{"description":"true: the character has no voice of its own.","type":"boolean","const":true},"clearPlannedClips":{"description":"Required when the project already has planned clips: a new picture, sheet or voice clears them (they were planned with the old look and must be planned again, which costs credits). Finished videos stay.","type":"boolean","const":true}},"additionalProperties":false},"example":{"mediaId":"66f7c0ffee00000000000004"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"characterId","in":"path","required":true,"schema":{"description":"The character's id (from studio_looks overview).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_.:-]+$"},"description":"The character's id (from studio_looks overview).","example":"character_mia"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"character":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"voice":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"seconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"url":{"type":"string"}},"required":["name","seconds","url"],"additionalProperties":false},{"type":"null"}]},"clipsCleared":{"type":"number"},"voices":{"type":"object","properties":{"used":{"type":"number"},"max":{"type":"number"},"seconds":{"type":"number"},"maxSeconds":{"type":"number"}},"required":["used","max","seconds","maxSeconds"],"additionalProperties":false}},"required":["projectId","character","voice","clipsCleared","voices"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/clip-jobs":{"get":{"operationId":"studio_clip_jobs_list","summary":"The film's 20 latest clip renders: status, video, what each cost, and why one failed.","description":"Lists the film's latest clip renders (also ones started in the app or by render_all), newest first: status, the video once made, the credits held and finally charged, and why a render failed, in plain words. The status shown is the last one stored; use get_job for a fresh check with the video model.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"studio.clip_jobs.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_clips action=list_jobs","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"jobs":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The clip render's id (its version id once it is made).","type":"string"},"clipId":{"type":"string"},"status":{"description":"preparing, queued, rendering, upscaling (the free 1080p), succeeded, failed, or billing_check (the model may have made it; its bill is being checked).","type":"string","enum":["preparing","queued","rendering","upscaling","succeeded","failed","billing_check"]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"upscaled":{"type":"boolean"},"continuesFrom":{"description":"The clip render this one continues from.","anyOf":[{"type":"string"},{"type":"null"}]},"creditsHeld":{"description":"Credits taken when it started.","type":"number"},"creditsCharged":{"description":"What it finally cost, once settled.","anyOf":[{"type":"number"},{"type":"null"}]},"billing":{"description":"authorized, settled, refunded or reconciliation_required.","type":"string"},"madeByBackupModel":{"description":"True when the main video model refused it and the backup model made it, for less.","type":"boolean"},"failure":{"anyOf":[{"type":"object","properties":{"category":{"type":"string"},"retryable":{"type":"boolean"},"message":{"type":"string"}},"required":["category","retryable","message"],"additionalProperties":false},{"type":"null"}]},"apiJobId":{"description":"The autoclips_jobs job that follows it, when it was started through the API.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","clipId","status","videoUrl","upscaled","continuesFrom","creditsHeld","creditsCharged","billing","madeByBackupModel","failure","apiJobId","createdAt","updatedAt"],"additionalProperties":false}}},"required":["projectId","jobs"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/clip-jobs/{clipJobId}":{"get":{"operationId":"studio_clips_get_job","summary":"One clip render, checked with the video model now (also a render started in the app).","description":"Checks one clip render with the video model now, as the app does while it waits: a finished clip is stored and settled, a failed one refunded, and the clip card updated. Works for any render of the film, also one started in the app or by render_all (renders started through the API are also followed by their autoclips_jobs job).\n\n**Permissions:** read.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"studio.clips.get_job","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_clips action=get_job","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"clipJobId","in":"path","required":true,"schema":{"description":"A clip render id from list_jobs (or clipJobId from render).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"A clip render id from list_jobs (or clipJobId from render).","example":"7c1e0a2b-3d4f-4a5b-8c6d-9e0f1a2b3c4d"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"job":{"type":"object","properties":{"id":{"description":"The clip render's id (its version id once it is made).","type":"string"},"clipId":{"type":"string"},"status":{"description":"preparing, queued, rendering, upscaling (the free 1080p), succeeded, failed, or billing_check (the model may have made it; its bill is being checked).","type":"string","enum":["preparing","queued","rendering","upscaling","succeeded","failed","billing_check"]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"upscaled":{"type":"boolean"},"continuesFrom":{"description":"The clip render this one continues from.","anyOf":[{"type":"string"},{"type":"null"}]},"creditsHeld":{"description":"Credits taken when it started.","type":"number"},"creditsCharged":{"description":"What it finally cost, once settled.","anyOf":[{"type":"number"},{"type":"null"}]},"billing":{"description":"authorized, settled, refunded or reconciliation_required.","type":"string"},"madeByBackupModel":{"description":"True when the main video model refused it and the backup model made it, for less.","type":"boolean"},"failure":{"anyOf":[{"type":"object","properties":{"category":{"type":"string"},"retryable":{"type":"boolean"},"message":{"type":"string"}},"required":["category","retryable","message"],"additionalProperties":false},{"type":"null"}]},"apiJobId":{"description":"The autoclips_jobs job that follows it, when it was started through the API.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","clipId","status","videoUrl","upscaled","continuesFrom","creditsHeld","creditsCharged","billing","madeByBackupModel","failure","apiJobId","createdAt","updatedAt"],"additionalProperties":false},"checked":{"description":"False when the video model could not be reached just now: the last stored state is shown.","type":"boolean"}},"required":["projectId","job","checked"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/clips/prepare":{"post":{"operationId":"studio_clips_prepare","summary":"Plan every clip of the film: an AI writes one direction per clip from the pictures. Paid; answers with a job.","description":"Plans the film's clips (the app's \"Prepare final clips\"): an AI reads the characters', places' and objects' pictures and the script, and writes one private direction per clip (4 to 30 seconds each). The frame and the voices it plans for are the film's saved ones (change them with studio_projects update before the clips exist). Paid: each AI call is billed at its real cost when it finishes; a call that fails is not charged. The quote (every call priced at its largest) is a hard cap: anything billed above it is given back, and if it is ever used up, planning stops and keeps what was paid for. It usually costs a fraction of it. It continues a planning run that stopped halfway, reusing what was already paid for, but only while nothing the run was planned from has changed. It replaces the planned clips: rendered clip videos stay in the clip history and finished films stay, but every clip must then be rendered again, so a film with rendered clips needs replaceRenderedClips: true. It runs in the background (several minutes for a long film): follow the job. It does not render anything.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"studio.clips.prepare","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"studio_clips action=prepare","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"planningModel":{"description":"Planning AI: Which AI plans the pictures, character sheets and clips from the script (it looks at the pictures, so only vision-capable writers). A new project starts on the app's pick for your plan.\nChoices:\n- opus55 — Claude Opus 5.5: Strongest physical logic and continuity for demanding stories. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 783 credits, a longer film or a bigger cast more (billed at the real AI cost).\n- trendScout — Kimi K3: Strong, timely, research-led story development. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 589 credits, a longer film or a bigger cast more (billed at the real AI cost).\n- quickSpark — Gemini 3.8 Flash: Fast brainstorming with clear visual beats. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 150 credits, a longer film or a bigger cast more (billed at the real AI cost).\nDefault: the planning AI saved on the film's clips (the one they were last planned with, or picked in the app's final clips step), else Kimi K3 (leave it out).","type":"string","enum":["opus55","trendScout","quickSpark"]},"replaceRenderedClips":{"description":"Needed when clips are already rendered: planning again replaces them, and every clip must be rendered again.","type":"boolean","const":true},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"job":{"description":"Follow it with autoclips_jobs get; it succeeds when every clip direction is written.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"planningModel":{"type":"string"},"clipsToPlan":{"description":"How many clips the plan will hold, as far as can be told now.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"resumed":{"description":"True when it continues planning that stopped halfway (the finished parts are free).","type":"boolean"},"resumeSkipped":{"description":"True when planning that stopped halfway earlier was not continued because the film changed since; it plans from the start.","type":"boolean"},"approvedCredits":{"description":"The most it costs (a hard cap); each AI call is charged as it finishes.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["projectId","job","planningModel","clipsToPlan","resumed","resumeSkipped","approvedCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19","job":{"id":"job_0192a3b4c5d6e7f8a9b0c1d2","product":"studio","kind":"studio.clip_plan","resource":{"type":"project","id":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},"status":"running","step":"Planning the clips","progress":null,"result":null,"error":null,"createdAt":"2026-09-29T10:00:00.000Z","updatedAt":"2026-09-29T10:00:00.000Z","finishedAt":null,"poll_after_seconds":20},"planningModel":"trendScout","clipsToPlan":3,"resumed":false,"resumeSkipped":false,"approvedCredits":2150}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/clips/recover":{"post":{"operationId":"studio_clips_recover","summary":"Put back the clip list behind the finished film when it went missing. Free.","description":"A finished film whose clip list is empty (a setting change or a cut-short planning cleared it) gets its clips back from the rendered clips and their directions, so they can be changed and re-rendered again. Free. Does nothing when the film already has clips.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.clips.recover","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_clips action=recover","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"recovered":{"type":"boolean"},"clips":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"number":{"anyOf":[{"type":"number"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"status":{"type":"string"},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","number","title","durationSeconds","status","videoUrl"],"additionalProperties":{}}},"message":{"type":"string"}},"required":["projectId","recovered","clips","message"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/clips/render":{"post":{"operationId":"studio_clips_render","summary":"Render one clip (or a few that do not follow each other) with the video model. Paid; each clip answers with a job.","description":"Renders the clips you name, each from its planned direction, with the film's pictures and character sheets; a clip after the first continues from the finished video of the clip before it, so that clip must be made first (to render several clips in a row, use render_all). Up to 6 clips at once, none of them the clip right after another in the list. A clip that already has a video needs newTake: true (a new take is charged again), or a changeRequest. changeRequest (one clip only) adds a sentence about what should differ to the clip's direction before rendering (free; for a deeper change use update). By default a re-rendered clip ends where the next clip begins (matchNextClip); join \"frames\" renders it from the last frame of the clip before to the first frame of the next. Paid per clip; the quote is the most it can cost. A clip that fails is refunded. Each clip answers with a job: follow it with autoclips_jobs get. When no clip starts, the error gives each clip's reason and what its credits did (details.clips).\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"studio.clips.render","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"studio_clips action=render","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clipIds":{"description":"The clips to render (1 to 6), none the clip right after another in the list.","minItems":1,"maxItems":6,"type":"array","items":{"description":"One clip of the film: its id from studio_projects get (include clips).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"changeRequest":{"description":"What should be different in this take, in plain words (one clip only, up to 3000 characters). It is added to the clip's direction.","type":"string","minLength":3,"maxLength":3000},"newTake":{"description":"Needed to render a clip that already has a finished video again (charged again).","type":"boolean","const":true},"matchNextClip":{"description":"Default true: when the next clip is already made, this clip is rendered to end where that one begins. false: its ending is free.","type":"boolean"},"join":{"description":"How clips join: How one clip continues into the next.\nChoices:\n- references — By references: Each clip follows the story and the character sheets. Works everywhere.\n- frames — Frame to frame: The clip starts on the last frame of the one before and ends where the next one begins. Needs the next clip.\nDefault: references.","type":"string","enum":["references","frames"]},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"required":["clipIds"],"additionalProperties":false},"example":{"clipIds":["segment-1"]}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"clips":{"type":"array","items":{"type":"object","properties":{"clipId":{"type":"string"},"number":{"anyOf":[{"type":"number"},{"type":"null"}]},"status":{"description":"started: a new take is rendering; already_rendering: a render of this clip was already going and is handed back (nothing charged); failed: see error.","type":"string","enum":["started","already_rendering","failed"]},"job":{"anyOf":[{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},{"type":"null"}]},"clipJobId":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsCharged":{"description":"Taken now (the list price); the final bill is in the job's result.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]}},"required":["clipId","number","status","job","clipJobId","creditsCharged","error"],"additionalProperties":false}},"creditsCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["projectId","clips","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/clips/{clipId}":{"patch":{"operationId":"studio_clips_update","summary":"Change one clip (lines, scenes, pictures, length, or in plain words); an AI rewrites its direction. Paid; does not render.","description":"Changes one clip the way the app's \"Update & render\" does, without the render: re-worded lines (lineEdits for characters, narrationEdits for the narrator), re-authored scenes (scriptEdits: what happens, where, and every line in order; the script is changed too), pictures added from or removed from the clip (removePictures, addPictures by their @name; pictureVersions to use another version of a picture), a new length (durationSeconds), and a sentence about what should differ (changeRequest). An AI then rewrites the clip's private direction around all of it (paid, billed at its real cost; a failed attempt is not charged). When the only change is a picture re-made since the clip was written or made (or another version of one picked), the rewrite is free (quoted 0, as in the app; catch_up does the same with nothing to approve) and counts toward the daily limit for free AI helpers. It runs in the background: follow the job. It does NOT render: render the clip afterwards with render (newTake: true); later clips keep their videos. durationSeconds: the clip's new length; its scenes are re-timed and later clips move along the timeline. It cannot be shorter than its lines need, nor over the talking-clip limit, and the next render is priced per second of it. When the change gives the clip more words than it holds, the quote says what length fits. matchNextClip: the rewrite describes an ending that meets the next clip's first frame (when the next clip is made).\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"studio.clips.update","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"studio_clips action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"changeRequest":{"description":"What should be different, in plain words.","type":"string","minLength":3,"maxLength":3000},"lineEdits":{"maxItems":60,"type":"array","items":{"type":"object","properties":{"lineIndex":{"description":"The line's position in the clip's spoken lines (0 is the first).","type":"integer","minimum":0,"maximum":59},"line":{"description":"The new words.","type":"string","minLength":1,"maxLength":3000},"from":{"description":"The words it replaces, as you saw them.","type":"string","maxLength":3000}},"required":["lineIndex","line"],"additionalProperties":false}},"narrationEdits":{"maxItems":24,"type":"array","items":{"type":"object","properties":{"sceneNumber":{"type":"integer","minimum":1,"maximum":24},"line":{"description":"The narrator's new words for that scene.","type":"string","minLength":1,"maxLength":5000},"from":{"type":"string","maxLength":5000}},"required":["sceneNumber","line"],"additionalProperties":false}},"scriptEdits":{"description":"The clip's scenes as they should now be: per scene what happens, where, and every spoken line in order (the shape rewrite_script answers with). At most 4 characters may speak in one clip, and the words must fit its length.","type":"object","properties":{"scenes":{"minItems":1,"maxItems":24,"type":"array","items":{"type":"object","properties":{"sceneNumber":{"type":"integer","minimum":1,"maximum":24},"visualAction":{"description":"What the camera sees in the scene, in present tense.","type":"string","minLength":1,"maxLength":5000},"locationId":{"description":"Where the scene plays: a place id from studio_projects get (include cast).","type":"string","minLength":1,"maxLength":120},"speech":{"description":"Every spoken line of the scene, in order (the whole list).","maxItems":12,"type":"array","items":{"type":"object","properties":{"kind":{"description":"dialogue: a character says it on camera; narration: the narrator's voice-over.","type":"string","enum":["dialogue","narration"]},"characterId":{"description":"Who says it (a character id from studio_projects get include cast); leave out for narration.","type":"string","minLength":1,"maxLength":120},"line":{"description":"The exact words, as they are said out loud.","type":"string","minLength":1,"maxLength":5000},"source":{"description":"Which existing line this row replaces (its position in the scene), so its delivery notes are kept; leave out for a new line.","type":"integer","minimum":0,"maximum":11}},"required":["kind","line"],"additionalProperties":false}}},"required":["sceneNumber"],"additionalProperties":false}}},"required":["scenes"],"additionalProperties":false},"removePictures":{"description":"Pictures this clip should stop using, by @name (as in the clip's references).","maxItems":16,"type":"array","items":{"type":"string","pattern":"^@?[A-Za-z0-9][A-Za-z0-9-]{0,79}$"}},"addPictures":{"description":"Pictures of the film's cast, places or objects this clip should use, by @name.","maxItems":16,"type":"array","items":{"type":"string","pattern":"^@?[A-Za-z0-9][A-Za-z0-9-]{0,79}$"}},"pictureVersions":{"description":"Use another version of a picture in this clip: its @name and the version id (studio_projects get include cast shows the versions).","maxItems":16,"type":"array","items":{"type":"object","properties":{"alias":{"type":"string","pattern":"^@?[A-Za-z0-9][A-Za-z0-9-]{0,79}$"},"versionId":{"description":"versionId","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"required":["alias","versionId"],"additionalProperties":false}},"removeAttachedIds":{"description":"Pictures attached to this clip in the app to take off it.","maxItems":4,"type":"array","items":{"description":"attachedId","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"useAttachedIds":{"description":"Pictures attached to this clip in the app that the direction should now use.","maxItems":4,"type":"array","items":{"description":"attachedId","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"matchNextClip":{"description":"true: end where the next clip begins (when it is made). Default false.","type":"boolean"},"durationSeconds":{"description":"The clip's new length in whole seconds. Clip length: One clip's length in whole seconds: 4 to 30, or at most 20 when a character talks on camera (a clip already planned longer keeps its own length within reach). It cannot be shorter than its spoken lines need. The clip's scenes and timings are re-timed and later clips move along the timeline, keeping their videos. The clip's next render is priced per second of the new length. From 4 to 30 seconds. Default: the clip keeps its current length (leave it out).","type":"integer","minimum":4,"maximum":30},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{"lineEdits":[{"lineIndex":0,"line":"We are not lost. We are exploring."}],"changeRequest":"Hold on Mia's face as she says it."}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"clipId","in":"path","required":true,"schema":{"description":"One clip of the film: its id from studio_projects get (include clips).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"One clip of the film: its id from studio_projects get (include clips).","example":"segment-2"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"clipId":{"type":"string"},"job":{"description":"Follow it with autoclips_jobs get; its result says what changed.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"approvedCredits":{"description":"The most the rewrite costs; 0 when it only catches the clip up with its pictures (free).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"free":{"description":"True when the rewrite only catches the clip up with its pictures (one re-made since the clip was written or made, or another version picked): nothing is charged for it, and it counts toward the daily limit for free AI helpers.","type":"boolean"},"lengthChange":{"description":"The clip's new length, when it changes.","anyOf":[{"type":"object","properties":{"fromSeconds":{"type":"number"},"toSeconds":{"type":"number"}},"required":["fromSeconds","toSeconds"],"additionalProperties":false},{"type":"null"}]}},"required":["projectId","clipId","job","approvedCredits","free","lengthChange"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/clips/{clipId}/catch-up":{"post":{"operationId":"studio_clips_catch_up","summary":"Rewrite one clip around pictures re-made since it was written, as the app does before it renders. Free; a job.","description":"A clip's direction describes the pictures it was written for. When one of them is re-made (or another version is picked for the clip), the clip cannot be rendered until its direction is rewritten around the new picture: render answers direction_behind_pictures. This rewrites it, exactly as the app's clip card does by itself before rendering, and it is free: nothing to approve. Refused when the clip's direction already describes the pictures it renders with (it renders as it is; a clip whose video alone is older than a picture just needs a new take), or when it has another pending change that makes the rewrite a paid edit (use update then). It runs in the background: follow the job, then render the clip (newTake: true when it already has a video). Counts toward the daily limit for free AI helpers.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.clips.catch_up","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_clips action=catch_up","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"clipId","in":"path","required":true,"schema":{"description":"One clip of the film: its id from studio_projects get (include clips).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"One clip of the film: its id from studio_projects get (include clips).","example":"segment-2"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"clipId":{"type":"string"},"job":{"description":"Follow it with autoclips_jobs get; its result says what changed.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"approvedCredits":{"description":"The most the rewrite costs; 0 when it only catches the clip up with its pictures (free).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"free":{"description":"True when the rewrite only catches the clip up with its pictures (one re-made since the clip was written or made, or another version picked): nothing is charged for it, and it counts toward the daily limit for free AI helpers.","type":"boolean"},"lengthChange":{"description":"The clip's new length, when it changes.","anyOf":[{"type":"object","properties":{"fromSeconds":{"type":"number"},"toSeconds":{"type":"number"}},"required":["fromSeconds","toSeconds"],"additionalProperties":false},{"type":"null"}]}},"required":["projectId","clipId","job","approvedCredits","free","lengthChange"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/clips/{clipId}/rewrite-script":{"post":{"operationId":"studio_clips_rewrite_script","summary":"Say in loose words how a clip's scenes should change; an AI proposes them in full (nothing is saved). Free.","description":"An AI rewrites one clip's scenes from your instruction (\"Vanessa keeps the laptop open and says the last line\"): what happens, where, and who says what, keeping everything you did not ask to change. Nothing is saved or rendered: show the proposal to the user, then apply it with update (scriptEdits, as answered here, and the same durationSeconds when you gave one). warnings lists rules the proposal still breaks (more words than the clip can say, more speakers than a clip can hold); fix those before applying. scenes (optional) are your unsaved edits to build on; durationSeconds (optional) the length the clip will have, so the words are fitted to it. Free; counts toward the daily limit for free AI helpers. Instruction up to 2000 characters.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.clips.rewrite_script","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_clips action=rewrite_script","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"instruction":{"description":"What should change, in your own words.","type":"string","minLength":2,"maxLength":2000},"scenes":{"description":"The clip's scenes as you are editing them (not saved yet), for the AI to build on. Default: the saved ones.","maxItems":24,"type":"array","items":{"type":"object","properties":{"sceneNumber":{"type":"integer","minimum":1,"maximum":24},"visualAction":{"type":"string","minLength":1,"maxLength":5000},"locationId":{"type":"string","minLength":1,"maxLength":120},"speech":{"maxItems":12,"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["dialogue","narration"]},"characterId":{"type":"string","minLength":1,"maxLength":120},"line":{"type":"string","minLength":1,"maxLength":5000}},"required":["kind","line"],"additionalProperties":false}}},"required":["sceneNumber"],"additionalProperties":false}},"durationSeconds":{"description":"The length the clip will have once you apply the proposal with update (send the same durationSeconds there), so the AI fits the words to it. Nothing is saved here. Clip length: One clip's length in whole seconds: 4 to 30, or at most 20 when a character talks on camera (a clip already planned longer keeps its own length within reach). It cannot be shorter than its spoken lines need. The clip's scenes and timings are re-timed and later clips move along the timeline, keeping their videos. The clip's next render is priced per second of the new length. From 4 to 30 seconds. Default: the words are fitted to the clip's current length (leave it out).","type":"integer","minimum":4,"maximum":30}},"required":["instruction"],"additionalProperties":false},"example":{"instruction":"Vanessa keeps the laptop open and says the last line."}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"clipId","in":"path","required":true,"schema":{"description":"One clip of the film: its id from studio_projects get (include clips).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"One clip of the film: its id from studio_projects get (include clips).","example":"segment-3"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"clipId":{"type":"string"},"scenes":{"description":"The proposed scenes in full.","type":"array","items":{"type":"object","properties":{"sceneNumber":{"type":"number"},"durationSeconds":{"type":"number"},"visualAction":{"type":"string"},"locationId":{"type":"string"},"speech":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"characterId":{"type":"string"},"speaker":{"type":"string"},"line":{"type":"string"},"source":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["kind","characterId","speaker","line","source"],"additionalProperties":false}}},"required":["sceneNumber","durationSeconds","visualAction","locationId","speech"],"additionalProperties":false}},"warnings":{"description":"Rules the proposal still breaks; fix them before applying.","type":"array","items":{"type":"string"}},"scriptEdits":{"description":"The proposal as an edit: send it as scriptEdits to update. Null when nothing changes.","anyOf":[{"type":"object","properties":{"scenes":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"required":["scenes"],"additionalProperties":false},{"type":"null"}]}},"required":["projectId","clipId","scenes","warnings","scriptEdits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/clips/{clipId}/version":{"put":{"operationId":"studio_clips_select_version","summary":"Choose which made version of a clip goes into the film (the app's version arrows). Free; join again to see it.","description":"Every render, new take and fix of a clip is kept as a version, and one of them is the clip's chosen version, the one the film is joined from. This chooses another, as the arrows on the app's clip card do. Free, and nothing is rendered: join the film again with stitch (free) to see it. The answer lists the clip's versions (list_jobs shows them too: a made clip render's id is its version id). A version that holds only the few seconds a fix rendered cannot be joined and is refused. The clip after it was rendered to continue from the version chosen then, so that join gets a slightly longer dissolve. Refused while the film is open in the app or anything else runs on it.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.clips.select_version","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_clips action=select_version","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"versionId":{"description":"The version to use: a made render of this clip (its id from this answer's versions, or a succeeded clip render in list_jobs).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"required":["versionId"],"additionalProperties":false},"example":{"versionId":"sj-5b1f0c2e-segment-2-a"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"clipId","in":"path","required":true,"schema":{"description":"One clip of the film: its id from studio_projects get (include clips).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"One clip of the film: its id from studio_projects get (include clips).","example":"segment-2"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"clipId":{"type":"string"},"number":{"anyOf":[{"type":"number"},{"type":"null"}]},"versionId":{"type":"string"},"changed":{"description":"False when it was already the chosen version.","type":"boolean"},"versions":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The version's id (the clip render that made it).","type":"string"},"number":{"description":"Its place among the clip's versions, oldest first, as the app's version arrows count them.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fix":{"description":"True for a fix of a few seconds of the clip (from the Review step); false for a render of the whole clip.","type":"boolean"},"whole":{"description":"False when it holds only the seconds a fix rendered, never joined back into the clip: the film cannot be joined from it.","type":"boolean"},"videoUrl":{"type":"string"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"selected":{"description":"True for the version the film is joined from.","type":"boolean"}},"required":["id","number","fix","whole","videoUrl","createdAt","selected"],"additionalProperties":false}},"message":{"type":"string"}},"required":["projectId","clipId","number","versionId","changed","versions","message"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/export":{"get":{"operationId":"studio_projects_export","summary":"Every file of a Studio project with a download link: pictures, sheets, clips, finished videos, music, script, captions.","description":"The project's files as the app's module pack has them: character and asset pictures and their versions, character sheets, reference pictures, voice references, every clip version, every finished video, the soundtrack and your own track, the script, and the titles, captions and thumbnails of the current video, plus a list of them all. Media files answer a link to where they are stored (checked just now: available false means the stored file is gone); text files come inline, up to about 256 KB together in one answer (a longer one says contentIncluded false: ask for it alone with fileId). The list of files the zip holds (manifest:public) comes only by fileId, since it repeats this answer. Only your own project's public fields are read: never the instructions sent to the picture and video models, and nothing from other accounts. Through MCP one answer holds as many files as fit, with up to about 20,000 characters of text inline (one text file by fileId: up to about 50,000); when has_more is true, send next_cursor as cursor for the rest. Over REST one answer holds every file. groups narrows the answer to some parts of the project. Free. When the answer carries a finished video and the free Review check still flags moments to fix in the film, review says how many, as the app asks before it downloads the film: tell the user, who can review them first (studio_review) or download it as it is.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"studio.projects.export","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_projects action=export","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from list or create).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"groups","in":"query","required":false,"schema":{"description":"Only these parts of the project: references, characters, assets, character_sheets, audio, clips, final_videos, script, publishing, manifest. Default: all.","minItems":1,"maxItems":10,"type":"array","items":{"type":"string","enum":["references","characters","assets","character_sheets","audio","clips","final_videos","script","publishing","manifest"]}},"description":"Only these parts of the project: references, characters, assets, character_sheets, audio, clips, final_videos, script, publishing, manifest. Default: all.","example":["final_videos","audio"]},{"name":"fileId","in":"query","required":false,"schema":{"description":"Just this one file (its id from a previous export), with its full text when it is a text file.","type":"string","minLength":1,"maxLength":300},"description":"Just this one file (its id from a previous export), with its full text when it is a text file.","example":"script:final"},{"name":"cursor","in":"query","required":false,"schema":{"description":"The next_cursor from the previous page.","type":"string","maxLength":512},"description":"The next_cursor from the previous page.","example":"eyJpIjo0MCwiaCI6IjNmMmE5YzBkMWU3YjQ0NTUiLCJnIjpudWxsfQ"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"title":{"type":"string"},"archiveName":{"description":"The zip's file name in the app.","type":"string"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The file's id in the pack (send it as fileId to get just this file).","type":"string"},"group":{"description":"Which part of the project: references, characters, assets, character_sheets, audio, clips, final_videos, script, publishing, manifest.","type":"string"},"label":{"type":"string"},"path":{"description":"Where the file sits in the app's download (the zip).","type":"string"},"kind":{"type":"string","enum":["image","video","audio","text"]},"url":{"description":"A link to the stored file (media only; text files come inline).","anyOf":[{"type":"string"},{"type":"null"}]},"sizeBytes":{"anyOf":[{"type":"number"},{"type":"null"}]},"available":{"description":"Whether the stored file answered when checked just now (null: not checked).","anyOf":[{"type":"boolean"},{"type":"null"}]},"content":{"description":"A text file's contents, when included.","anyOf":[{"type":"string"},{"type":"null"}]},"contentIncluded":{"description":"False when a text file's contents are not in this answer (too long for it, or the list of files, which repeats this answer): ask for it alone with fileId.","type":"boolean"},"details":{"type":"object","properties":{},"additionalProperties":{}}},"required":["id","group","label","path","kind","url","sizeBytes","available","details"],"additionalProperties":false}},"fileCount":{"description":"Files in this answer.","type":"number"},"totalFiles":{"description":"Files in the chosen groups, over every page.","type":"number"},"totalBytes":{"description":"The sizes known after the check, added up (this answer's files).","type":"number"},"checked":{"description":"Whether the stored files were checked just now.","type":"boolean"},"unavailable":{"description":"Files in this answer whose stored copy did not answer.","type":"array","items":{"type":"string"}},"next_cursor":{"description":"When has_more is true: send it as cursor (with the same groups) for the next page.","anyOf":[{"type":"string"},{"type":"null"}]},"has_more":{"type":"boolean"},"review":{"description":"Set when this answer carries a finished video and the free Review check still flags moments to fix in the film: the app asks before it downloads the film then. Fixing is optional; the files are ready either way.","anyOf":[{"type":"object","properties":{"toFix":{"description":"Moments the free Review check still flags to fix in the film's clips.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"note":{"type":"string"}},"required":["toFix","note"],"additionalProperties":false},{"type":"null"}]},"note":{"type":"string"},"links":{"type":"object","properties":{"app":{"type":"string"}},"required":["app"],"additionalProperties":{}}},"required":["projectId","title","archiveName","files","fileCount","totalFiles","totalBytes","checked","unavailable","next_cursor","has_more","review","note","links"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"projectId":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e","title":"The Last Lighthouse","archiveName":"the-last-lighthouse-module-pack.zip","files":[{"id":"final:final-video-7c1e","group":"final_videos","label":"Studio cut 1","path":"final-videos/studio-version-1.mp4","kind":"video","url":"https://media.autoclips.app/kling-videos/studio-v2/user-id/final/final-video-7c1e.mp4","sizeBytes":18234567,"available":true,"details":{"versionId":"final-video-7c1e","source":"studio","parentVersionId":"","duration":30}},{"id":"script:final","group":"script","label":"Final script","path":"script/final-script.txt","kind":"text","url":null,"sizeBytes":64,"available":true,"content":"The Last Lighthouse\nThree keepers vanish.\n\nScene 1. The storm.","contentIncluded":true,"details":{"storyMode":"mixed"}}],"fileCount":2,"totalFiles":2,"totalBytes":18234631,"checked":true,"unavailable":[],"next_cursor":null,"has_more":false,"review":null,"note":"Media files link to where they are stored (the same files the app shows); text files come inline. In the app (links.app), Final video, Your production files, Download all files gives the same files as one zip.","links":{"app":"https://app.autoclips.app/studio-2?projectId=b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/looks":{"get":{"operationId":"studio_looks_get","summary":"What each character, object and place has: direction, picture, references, sheet and voice, and what the next steps cost.","description":"Shows every character, object and place of a Studio project: whether its picture direction is written, its picture, its reference pictures and, for characters, the character sheet and voice. Also the picture makers' prices, the voice limits, and what to do next. Free.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"studio.looks.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_looks action=overview","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"hasScript":{"type":"boolean"},"clipsPlanned":{"description":"Clips already planned. A new picture, sheet or voice clears them.","type":"number"},"settings":{"type":"object","properties":{"imageModel":{"type":"string"},"sheetImageModel":{"type":"string"},"planningModel":{"type":"string"},"sheetPlanningModel":{"type":"string"}},"required":["imageModel","sheetImageModel","planningModel","sheetPlanningModel"],"additionalProperties":{}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["character","object","place"]},"name":{"type":"string"},"canHavePicture":{"description":"False for fixed furniture, which is drawn as part of its place.","type":"boolean"},"direction":{"description":"The picture direction make_pictures draws from: ready; missing (none yet); or outdated (written before Studio could see this item's reference pictures). A missing or outdated one is written by prepare_pictures before the item is drawn, as the app does; an item that already has its picture keeps its direction as it is until you name the item to draw it again.","type":"string","enum":["ready","missing","outdated"]},"picture":{"description":"The picture the film uses. source \"yours\": your own picture, used as it is: nothing is drawn for it. To draw it from that picture, name it in prepare_pictures first (the app's \"Draw from it\"), then in make_pictures.","anyOf":[{"type":"object","properties":{"url":{"type":"string"},"versionId":{"type":"string"},"source":{"type":"string","enum":["made","yours"]}},"required":["url","versionId","source"],"additionalProperties":{}},{"type":"null"}]},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"}},"required":["id","name","url"],"additionalProperties":{}}}},"required":["id","kind","name","canHavePicture","direction","picture","references"],"additionalProperties":{}}},"voices":{"type":"object","properties":{"used":{"type":"number"},"max":{"type":"number"},"seconds":{"type":"number"},"maxSeconds":{"type":"number"},"allowed":{"type":"boolean"}},"required":["used","max","seconds","maxSeconds","allowed"],"additionalProperties":{}},"prices":{"description":"The most a picture costs per picture maker (with no references), and a character sheet.","type":"object","properties":{},"additionalProperties":{}},"next":{"description":"What to do next, in plain words.","type":"array","items":{"type":"string"}}},"required":["projectId","hasScript","clipsPlanned","settings","items","voices","prices","next"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/outro":{"post":{"operationId":"studio_finish_outro","summary":"Add an outro from your outro library after the last scene, or take it off. Answers with a job.","description":"Joins one of your outros (an end card with your handles, website or logo; list them with list_outros) after the last scene of a finished video and makes that the film's video. Free. To keep a watermark, add the outro to the watermarked version (its id is in the watermark job's result). A video that already ends with an outro is swapped for the version without it first. Runs in the background (it may render the card first): follow the job. outroId \"none\" takes the outro off by switching back to the version without it. Refused while the film is open in the AutoClips app or anything else runs on it.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.finish.outro","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_finish action=outro","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceVideoId":{"description":"Which finished video gets the outro. Default: the film's current video.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"outroId":{"description":"The outro to add, from list_outros, or \"none\" to take the outro off. Default: the outro saved on the film.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"additionalProperties":false},"example":{"outroId":"5f0c2b7e-8a41-4d6f-9b3a-2e1c7d9f0a11"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"started":{"description":"True when background work started; follow it with autoclips_jobs get.","type":"boolean"},"job":{"description":"The background work, when some started.","anyOf":[{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},{"type":"null"}]},"video":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"aspectRatio":{"anyOf":[{"type":"string"},{"type":"null"}]},"watermark":{"description":"The watermark burned into this version, if any.","anyOf":[{"type":"string","enum":["text","image"]},{"type":"null"}]},"outro":{"description":"Whether this version ends with an outro.","type":"boolean"},"builtOn":{"description":"The version this one was made from.","anyOf":[{"type":"string"},{"type":"null"}]},"speed":{"description":"How fast this video plays: 1 = as rendered, 1.25 = a quarter faster (voices keep their pitch).","type":"number"},"selected":{"description":"Whether this is the film's current video.","type":"boolean"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","url","durationSeconds","aspectRatio","watermark","outro","builtOn","speed","selected","createdAt"],"additionalProperties":false},{"type":"null"}]},"builtOn":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"aspectRatio":{"anyOf":[{"type":"string"},{"type":"null"}]},"watermark":{"description":"The watermark burned into this version, if any.","anyOf":[{"type":"string","enum":["text","image"]},{"type":"null"}]},"outro":{"description":"Whether this version ends with an outro.","type":"boolean"},"builtOn":{"description":"The version this one was made from.","anyOf":[{"type":"string"},{"type":"null"}]},"speed":{"description":"How fast this video plays: 1 = as rendered, 1.25 = a quarter faster (voices keep their pitch).","type":"number"},"selected":{"description":"Whether this is the film's current video.","type":"boolean"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","url","durationSeconds","aspectRatio","watermark","outro","builtOn","speed","selected","createdAt"],"additionalProperties":false},{"type":"null"}]},"outroId":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"type":"string"}},"required":["projectId","started","job","video","builtOn","outroId","message"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/pictures":{"post":{"operationId":"studio_images_generate","summary":"Draw the pictures of characters, objects and places from their directions. Each is a new version. Costs credits; answers with a job.","description":"Draws a picture for each item from its direction (write the directions first with prepare_pictures), using its reference pictures. Each picture is a new version and becomes the one the film uses; older versions stay. items: which ones, by id. Or leave items out for every item still without a picture (kind: characters or objects_and_places narrows it; redo: true draws every item again). Without items, an item that uses your own picture as it is is never drawn over, as in the app. To draw it from that picture, name it in prepare_pictures first (the app's \"Draw from it\"), then in make_pictures. Every item drawn needs a picture direction written with its reference pictures in view: one that is missing, or outdated (written before Studio could see them), is refused with needs_direction; write it first with prepare_pictures, naming the item (the app does that step itself before it draws). change: with exactly one item, what to change in its current picture, in your own words; the current picture is sent as a reference. imageModel: the picture maker (default: the project's picture maker, else dream5). Priced per picture by the model and the references sent; the quote is the most it can cost, including a backup provider billed at its own rate, and you are never charged more than it. A picture that fails is refunded. If the project already has planned clips, new pictures clear them (they were planned with the old look): send clearPlannedClips: true to go ahead; an AI app asks first. Runs in the background: the answer is a job (autoclips_jobs get). Refused while anything else runs on the project, and, when it clears planned clips, while the project is open and saving in the app.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"studio.images.generate","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"studio_looks action=make_pictures","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"description":"The characters, objects and places to draw, by id. Default: every item still without a picture.","minItems":1,"maxItems":30,"type":"array","items":{"description":"The id of a character, object or place (from studio_looks overview).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_.:-]+$"}},"kind":{"description":"Without items: only the characters, or only the objects and places.","type":"string","enum":["characters","objects_and_places"]},"redo":{"description":"Without items: true draws a new version of every item, including those that already have a picture, except those that use your own picture as it is. Default false.","type":"boolean"},"change":{"description":"Only with exactly one item: what to change in its current picture, in your own words (up to 3,000 characters), for example \"make the coat red\". The current picture is sent as a reference.","type":"string","minLength":3,"maxLength":3000},"imageModel":{"description":"Picture maker: Which model draws the characters, places, objects and character sheets.\nChoices:\n- dream5 — Dream 5: Recommended for polished 3D character and asset references. (41 credits per picture)\n- gptImage2High — ChatGPT Image 2.0 High: Strong prompt accuracy and crisp production detail. (30 credits per picture)\n- nanoBanana2 — Nano Banana 2: Fast high-quality generations with flexible references. (72 credits per picture)\nDefault: the project's picture maker, else dream5 (leave it out).","type":"string","enum":["dream5","gptImage2High","nanoBanana2"]},"clearPlannedClips":{"description":"Required when the project already has planned clips: a new picture, sheet or voice clears them (they were planned with the old look and must be planned again, which costs credits). Finished videos stay.","type":"boolean","const":true},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"started":{"type":"boolean","const":true},"job":{"description":"Follow it with autoclips_jobs get (or GET /v1/jobs/{id}); its result says what was made and what was charged.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"drawing":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"}},"required":["id","name","kind"],"additionalProperties":false}},"leftAlone":{"description":"Without items: the items that use your own picture as it is, so they are not drawn over.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"}},"required":["id","name","kind"],"additionalProperties":false}},"imageModel":{"type":"string"},"clipsToClear":{"description":"Planned clips that are cleared once a new picture lands.","type":"number"}},"required":["projectId","started","job","drawing","imageModel","clipsToClear"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19","started":true,"job":{"id":"job_0192f1a2b3c4d5e6f7a8b9c0","product":"studio","kind":"studio.pictures","resource":{"type":"project","id":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},"status":"running","step":"Drawing pictures","progress":null,"result":null,"error":null,"createdAt":"2026-09-29T10:00:00.000Z","updatedAt":"2026-09-29T10:00:00.000Z","finishedAt":null,"poll_after_seconds":20},"drawing":[{"id":"location_lighthouse","name":"The lighthouse","kind":"place"}],"imageModel":"dream5","clipsToClear":4}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/pictures/directions":{"post":{"operationId":"studio_images_prepare","summary":"The planning AI writes a picture direction for each character, object and place. Needed before make_pictures. Costs credits.","description":"The planning AI looks at the studio's house style and at each item's own reference pictures, and writes, for each item, the direction its picture is drawn from (two items per request, characters and the rest separately, exactly as the app does). It is needed once per item before make_pictures; items that already have one are skipped, except a direction written before Studio could see the item's reference pictures (overview shows it as outdated), which is written again, as the app does before it draws. items: the ids of the characters, objects and places (from overview). Leave it out for the items make_pictures draws without items (those still without a picture) whose direction is missing or outdated: as in the app, a direction is written only for an item about to be drawn, so an item that already has its picture keeps its direction until you name it to draw it again. Items that use your own picture as it is are left out too (nothing is drawn for them, as in the app). Name such an item to draw it from that picture, like the app's \"Draw from it\": the picture becomes its first reference photo and the direction is written from it; then name it in make_pictures. Fixed furniture is drawn as part of its place and is refused. planningModel: which AI writes them (default: the project's saved planning AI, else Kimi K3). Billed at the AI's actual cost after each request; the quote is the most it can cost (the real prompt counted generously and the longest answer the request allows), and you are never charged more than the price you approved. A request that fails costs nothing. Studio needs 500 credits in your balance to start these requests. Runs in the background: the answer is a job (autoclips_jobs get). Refused while the project is open and saving in the app, and while anything else runs on it.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"studio.images.prepare","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"studio_looks action=prepare_pictures","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"description":"The characters, objects and places to prepare, by id. Default: every item still without a picture whose picture direction is missing or outdated (the items make_pictures draws without items), except those that use your own picture as it is.","minItems":1,"maxItems":30,"type":"array","items":{"description":"The id of a character, object or place (from studio_looks overview).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_.:-]+$"}},"planningModel":{"description":"Planning AI: Which AI plans the pictures, character sheets and clips from the script (it looks at the pictures, so only vision-capable writers). A new project starts on the app's pick for your plan.\nChoices:\n- opus55 — Claude Opus 5.5: Strongest physical logic and continuity for demanding stories. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 783 credits, a longer film or a bigger cast more (billed at the real AI cost).\n- trendScout — Kimi K3: Strong, timely, research-led story development. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 589 credits, a longer film or a bigger cast more (billed at the real AI cost).\n- quickSpark — Gemini 3.8 Flash: Fast brainstorming with clear visual beats. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 150 credits, a longer film or a bigger cast more (billed at the real AI cost).\nDefault: the project's saved planning AI, else Kimi K3 (leave it out).","type":"string","enum":["opus55","trendScout","quickSpark"]},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"started":{"type":"boolean","const":true},"job":{"description":"Follow it with autoclips_jobs get (or GET /v1/jobs/{id}); its result says what was made and what was charged.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"preparing":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"}},"required":["id","name","kind"],"additionalProperties":false}},"rewriting":{"description":"Those of preparing whose direction was written before Studio could see their reference pictures: written again, as the app does.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"}},"required":["id","name","kind"],"additionalProperties":false}},"fromYourPicture":{"description":"Those of preparing you named that use your own picture as it is: like the app's \"Draw from it\", the picture became their first reference photo and the direction is written from it; name them in make_pictures to draw them from it.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"}},"required":["id","name","kind"],"additionalProperties":false}},"skipped":{"description":"Items that already have a direction.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"}},"required":["id","name","kind"],"additionalProperties":false}},"leftAlone":{"description":"Items that use your own picture as it is: nothing is drawn for them, so they get no direction unless you name them in items.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"}},"required":["id","name","kind"],"additionalProperties":false}},"planningModel":{"type":"string"},"requests":{"description":"How many requests to the planning AI (two items each).","type":"number"}},"required":["projectId","started","job","preparing","rewriting","fromYourPicture","skipped","leftAlone","planningModel","requests"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/promotion":{"get":{"operationId":"studio_promotion_get","summary":"The product a Studio film promotes: its details, placement, call to action and pictures.","description":"The promotion saved on the project, or null when it promotes nothing. canChange says whether it can still change (only before the script is written).\n\n**Permissions:** read.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"studio.promotion.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_ideas action=get_promotion","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects list or create).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"promotion":{"description":"The product this film promotes, or null.","anyOf":[{"type":"object","properties":{"source":{"description":"Where the details came from: manual, website, brand, or detected (Studio found the product in the idea).","type":"string"},"product":{"type":"object","properties":{"name":{"type":"string"},"productType":{"type":"string"},"whatItIs":{"type":"string"},"benefits":{"type":"array","items":{"type":"string"}},"differentiators":{"type":"array","items":{"type":"string"}},"audience":{"type":"string"},"tone":{"type":"string"}},"required":["name","productType","whatItIs","benefits","differentiators","audience","tone"],"additionalProperties":false},"placement":{"type":"string","enum":["end","middle","throughout"]},"placementChosen":{"description":"True when the placement was picked, not left to the default.","type":"boolean"},"callToAction":{"anyOf":[{"type":"string"},{"type":"null"}]},"website":{"anyOf":[{"type":"string"},{"type":"null"}]},"brandId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pictures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"role":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","url","role"],"additionalProperties":false}},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","product","placement","placementChosen","callToAction","website","brandId","pictures","updatedAt"],"additionalProperties":false},{"type":"null"}]},"canChange":{"description":"False once the script is written (the promotion shaped it).","type":"boolean"},"note":{"type":"string"}},"required":["projectId","promotion","canChange","note"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"studio_promotion_set","summary":"Set the product a Studio film promotes: details, placement, call to action, pictures. Free.","description":"Saves the product the film promotes, or changes it: the fields you send replace those fields, the rest stay (a first promotion needs product.name). placement: end (the product comes in at the end, after the story; the default), middle (one natural product moment in the middle of the story), throughout (the product is part of the story from start to end). pictures (up to 4) is the whole new list: a mediaId adds a picture from your media library (JPG, PNG or WebP, up to 10 MB; copied into Studio), a pictureId keeps one it already has; leave pictures out to keep them as they are. website (a link, only shown in the film's call to action, never visited) or brandId (one of your brands, Pro and up) records where the details came from; website \"\" clears it. Changing the product or its placement makes an existing brief stale: write a new one with write_brief. Only before the script is written, and not while the project is open and being edited in the app or while Studio works on it. Adding pictures counts toward the daily upload limit. An app tab that had the project open before this change keeps it when it saves. One exception: in an app tab opened after this change, a very first change that puts things back as they were (for example removing a promotion or a brief the API added) does not stick, and the API's version stays. To take it back, use remove_promotion or discard_brief here, or make any other change in that tab first and then remove it.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.promotion.set","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_ideas action=set_promotion","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product":{"description":"The product details (from extract_product, or the user's own words).","type":"object","properties":{"name":{"description":"The product's name (up to 120 characters).","type":"string","minLength":1,"maxLength":120},"productType":{"description":"What kind of product it is, which decides how it appears in the film: packaged-goods (Packaged product), supplement (Supplement), skincare (Skincare), beauty (Make-up / beauty), cleaning (Cleaning product), food (Food), drink (Drink), electronics (Electronics / device), home-goods (Home goods), storage (Storage / organisation), furniture (Furniture), book (Book), apparel (Clothing / accessories), pet (Pet product), saas (Software / SaaS), mobile-app (Mobile app), course (Course / membership), service (Service).","type":"string","enum":["packaged-goods","supplement","skincare","beauty","cleaning","food","drink","electronics","home-goods","storage","furniture","book","apparel","pet","saas","mobile-app","course","service"]},"whatItIs":{"description":"What it is, in one sentence (up to 300 characters).","type":"string","maxLength":300},"benefits":{"description":"Up to 5 benefits, each up to 200 characters.","maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"differentiators":{"description":"Up to 3 things that set it apart.","maxItems":3,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"audience":{"description":"Who it is for.","type":"string","maxLength":300},"tone":{"description":"How the brand sounds (for example \"warm and playful\").","type":"string","maxLength":120}},"additionalProperties":false},"placement":{"description":"Where the product appears: end (the product comes in at the end, after the story; the default), middle (one natural product moment in the middle of the story), throughout (the product is part of the story from start to end).","type":"string","enum":["end","middle","throughout"]},"callToAction":{"description":"What viewers should do, in a few words (for example \"Try it free at cozypaws.com\"). \"\" clears it.","type":"string","maxLength":200},"website":{"description":"The product's page, shown in the call to action (never visited). \"\" clears it.","type":"string","maxLength":2000,"pattern":"^(https?:\\/\\/\\S+)?$"},"brandId":{"description":"One of your brands (Pro and up): its id from the brands list in the app.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"pictures":{"description":"The pictures, as the whole new list (up to 4). [] removes them all.","maxItems":4,"type":"array","items":{"type":"object","properties":{"mediaId":{"description":"A picture from your media library (autoclips_media); it is copied into Studio.","type":"string","pattern":"^[a-fA-F0-9]{24}$"},"pictureId":{"description":"A picture the promotion already has (its id from get_promotion), to keep it.","type":"string","minLength":1,"maxLength":120}},"additionalProperties":false}}},"additionalProperties":false},"example":{"product":{"name":"CozyPaws Heated Bed","productType":"pet","whatItIs":"A heated bed for older dogs.","benefits":["Warm all night","Washable cover"]},"placement":"end","callToAction":"Find it at cozypaws.com","website":"https://cozypaws.com/heated-bed","pictures":[{"mediaId":"66f7c0ffee00000000000001"}]}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects list or create).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"promotion":{"description":"The product this film promotes, or null.","anyOf":[{"type":"object","properties":{"source":{"description":"Where the details came from: manual, website, brand, or detected (Studio found the product in the idea).","type":"string"},"product":{"type":"object","properties":{"name":{"type":"string"},"productType":{"type":"string"},"whatItIs":{"type":"string"},"benefits":{"type":"array","items":{"type":"string"}},"differentiators":{"type":"array","items":{"type":"string"}},"audience":{"type":"string"},"tone":{"type":"string"}},"required":["name","productType","whatItIs","benefits","differentiators","audience","tone"],"additionalProperties":false},"placement":{"type":"string","enum":["end","middle","throughout"]},"placementChosen":{"description":"True when the placement was picked, not left to the default.","type":"boolean"},"callToAction":{"anyOf":[{"type":"string"},{"type":"null"}]},"website":{"anyOf":[{"type":"string"},{"type":"null"}]},"brandId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pictures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"role":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","url","role"],"additionalProperties":false}},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","product","placement","placementChosen","callToAction","website","brandId","pictures","updatedAt"],"additionalProperties":false},{"type":"null"}]},"canChange":{"description":"False once the script is written (the promotion shaped it).","type":"boolean"},"note":{"type":"string"},"picturesAdded":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["projectId","promotion","canChange","note","picturesAdded"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"studio_promotion_remove","summary":"Stop promoting a product in a Studio film: its details and pictures are removed. Free.","description":"Removes the promotion from the project, so the script promotes nothing. This is the sure way to take back a promotion the API added: in an app tab opened after it was added, removing it as the very first change there does not stick. Only before the script is written, and not while the project is open and being edited in the app or while Studio works on it. In AI apps it asks first.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.promotion.remove","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_ideas action=remove_promotion","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects list or create).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"promotion":{"description":"The product this film promotes, or null.","anyOf":[{"type":"object","properties":{"source":{"description":"Where the details came from: manual, website, brand, or detected (Studio found the product in the idea).","type":"string"},"product":{"type":"object","properties":{"name":{"type":"string"},"productType":{"type":"string"},"whatItIs":{"type":"string"},"benefits":{"type":"array","items":{"type":"string"}},"differentiators":{"type":"array","items":{"type":"string"}},"audience":{"type":"string"},"tone":{"type":"string"}},"required":["name","productType","whatItIs","benefits","differentiators","audience","tone"],"additionalProperties":false},"placement":{"type":"string","enum":["end","middle","throughout"]},"placementChosen":{"description":"True when the placement was picked, not left to the default.","type":"boolean"},"callToAction":{"anyOf":[{"type":"string"},{"type":"null"}]},"website":{"anyOf":[{"type":"string"},{"type":"null"}]},"brandId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pictures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"role":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","url","role"],"additionalProperties":false}},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","product","placement","placementChosen","callToAction","website","brandId","pictures","updatedAt"],"additionalProperties":false},{"type":"null"}]},"canChange":{"description":"False once the script is written (the promotion shaped it).","type":"boolean"},"note":{"type":"string"},"removed":{"type":"boolean"}},"required":["projectId","promotion","canChange","note","removed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/promotion/brand-pictures":{"post":{"operationId":"studio_promotion_import","summary":"Add pictures (and the logo) of one of your brands to the product a Studio film promotes. Pro and up.","description":"Copies pictures from one of your brands (and its logo, with includeLogo) into Studio and adds them to the film's promotion, up to 4 pictures in all. assetIds are the brand's picture ids (see your brands in the app, or the brands API). Set the product first (set_promotion). Brands come with the Pro plan and higher. Only before the script is written, and not while the project is open and being edited in the app or while Studio works on it. Counts toward the daily upload limit. An app tab that had the project open before this change keeps it when it saves. One exception: in an app tab opened after this change, a very first change that puts things back as they were (for example removing a promotion or a brief the API added) does not stick, and the API's version stays. To take it back, use remove_promotion or discard_brief here, or make any other change in that tab first and then remove it.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.promotion.import","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_ideas action=import_brand_pictures","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"description":"One of your brands (Pro and up): its id from the brands list in the app.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"assetIds":{"description":"The brand's pictures to add (up to 4).","maxItems":4,"type":"array","items":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_.:-]+$"}},"includeLogo":{"description":"Also add the brand's logo. Default false.","type":"boolean"}},"required":["brandId"],"additionalProperties":false},"example":{"brandId":"brand_7f3a91","assetIds":["asset_1a2b","asset_3c4d"],"includeLogo":true}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects list or create).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"promotion":{"description":"The product this film promotes, or null.","anyOf":[{"type":"object","properties":{"source":{"description":"Where the details came from: manual, website, brand, or detected (Studio found the product in the idea).","type":"string"},"product":{"type":"object","properties":{"name":{"type":"string"},"productType":{"type":"string"},"whatItIs":{"type":"string"},"benefits":{"type":"array","items":{"type":"string"}},"differentiators":{"type":"array","items":{"type":"string"}},"audience":{"type":"string"},"tone":{"type":"string"}},"required":["name","productType","whatItIs","benefits","differentiators","audience","tone"],"additionalProperties":false},"placement":{"type":"string","enum":["end","middle","throughout"]},"placementChosen":{"description":"True when the placement was picked, not left to the default.","type":"boolean"},"callToAction":{"anyOf":[{"type":"string"},{"type":"null"}]},"website":{"anyOf":[{"type":"string"},{"type":"null"}]},"brandId":{"anyOf":[{"type":"string"},{"type":"null"}]},"pictures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"role":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","url","role"],"additionalProperties":false}},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","product","placement","placementChosen","callToAction","website","brandId","pictures","updatedAt"],"additionalProperties":false},{"type":"null"}]},"canChange":{"description":"False once the script is written (the promotion shaped it).","type":"boolean"},"note":{"type":"string"},"picturesAdded":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"description":"Brand pictures that could not be copied.","type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"reason":{"type":"string"}},"required":["name","reason"],"additionalProperties":false}}},"required":["projectId","promotion","canChange","note","picturesAdded","failed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/publishing/headline":{"post":{"operationId":"studio_publishing_headline","summary":"Put new headline words on a thumbnail you already made (no new picture).","description":"Redraws the words on the chosen thumbnail of the film's publishing package, on the same picture (no AI picture, no credits), and makes it the chosen thumbnail. The headline becomes the package's headline. Up to 90 characters. Refused while the film is open in the AutoClips app or anything else runs on it.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.publishing.headline","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_publishing action=headline","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ratio":{"description":"Thumbnail shapes: Which thumbnail shapes to make for the publishing package.\nChoices:\n- 9:16 — 9:16: A 9:16 thumbnail.\n- 1:1 — 1:1: A 1:1 thumbnail.\n- 16:9 — 16:9: A 16:9 thumbnail.","type":"string","enum":["9:16","1:1","16:9"]},"headline":{"description":"The words on the thumbnail, 2 to 6 words work best, up to 90 characters.","type":"string","minLength":1,"maxLength":90}},"required":["ratio","headline"],"additionalProperties":false},"example":{"ratio":"9:16","headline":"He kept the light on"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"ratio":{"type":"string"},"thumbnail":{"type":"object","properties":{"id":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"ratio":{"anyOf":[{"type":"string"},{"type":"null"}]},"width":{"anyOf":[{"type":"number"},{"type":"null"}]},"height":{"anyOf":[{"type":"number"},{"type":"null"}]},"headline":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageModel":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsCharged":{"type":"number"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","url","ratio","width","height","headline","imageModel","creditsCharged","createdAt"],"additionalProperties":false},"package":{"type":"object","properties":{"id":{"type":"string"},"videoId":{"description":"The finished video this copy was written for.","anyOf":[{"type":"string"},{"type":"null"}]},"headline":{"description":"The words drawn on the thumbnails.","anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","properties":{"youtube":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","tags","hashtags"],"additionalProperties":false},"tiktok":{"type":"object","properties":{"caption":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["caption","hashtags"],"additionalProperties":false},"instagram":{"type":"object","properties":{"caption":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["caption","hashtags"],"additionalProperties":false}},"required":["youtube","tiktok","instagram"],"additionalProperties":false},"thumbnails":{"description":"The chosen thumbnail per shape (9:16, 1:1, 16:9), or null.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"ratio":{"anyOf":[{"type":"string"},{"type":"null"}]},"width":{"anyOf":[{"type":"number"},{"type":"null"}]},"height":{"anyOf":[{"type":"number"},{"type":"null"}]},"headline":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageModel":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsCharged":{"type":"number"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","url","ratio","width","height","headline","imageModel","creditsCharged","createdAt"],"additionalProperties":false},{"type":"null"}]}},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","videoId","headline","metadata","thumbnails","createdAt"],"additionalProperties":false}},"required":["projectId","ratio","thumbnail","package"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/publishing/metadata":{"post":{"operationId":"studio_publishing_metadata","summary":"Write the YouTube title and description, TikTok and Instagram captions, hashtags and a thumbnail headline.","description":"An AI editor who watched the film writes its publishing copy for the film's current video: a YouTube title, description, tags and hashtags, TikTok and Instagram captions with hashtags, and a short headline for the thumbnails. It is saved as a new publishing package (earlier ones are kept). Free; counts toward the daily limit for free AI helpers. Thumbnails are made separately with thumbnail (paid).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.publishing.metadata","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_publishing action=metadata","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ratios":{"uniqueItems":true,"description":"Thumbnail shapes: Which thumbnail shapes to make for the publishing package. Pick any of: 9:16, 1:1, 16:9. Each at most once. Default: The film's own shape (leave it out).","type":"array","items":{"description":"Thumbnail shapes: Which thumbnail shapes to make for the publishing package.\nChoices:\n- 9:16 — 9:16: A 9:16 thumbnail.\n- 1:1 — 1:1: A 1:1 thumbnail.\n- 16:9 — 16:9: A 16:9 thumbnail.","type":"string","enum":["9:16","1:1","16:9"]}}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"package":{"type":"object","properties":{"id":{"type":"string"},"videoId":{"description":"The finished video this copy was written for.","anyOf":[{"type":"string"},{"type":"null"}]},"headline":{"description":"The words drawn on the thumbnails.","anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","properties":{"youtube":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","tags","hashtags"],"additionalProperties":false},"tiktok":{"type":"object","properties":{"caption":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["caption","hashtags"],"additionalProperties":false},"instagram":{"type":"object","properties":{"caption":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["caption","hashtags"],"additionalProperties":false}},"required":["youtube","tiktok","instagram"],"additionalProperties":false},"thumbnails":{"description":"The chosen thumbnail per shape (9:16, 1:1, 16:9), or null.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"ratio":{"anyOf":[{"type":"string"},{"type":"null"}]},"width":{"anyOf":[{"type":"number"},{"type":"null"}]},"height":{"anyOf":[{"type":"number"},{"type":"null"}]},"headline":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageModel":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsCharged":{"type":"number"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","url","ratio","width","height","headline","imageModel","creditsCharged","createdAt"],"additionalProperties":false},{"type":"null"}]}},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","videoId","headline","metadata","thumbnails","createdAt"],"additionalProperties":false},"reused":{"description":"True when this request was already answered (a retry).","type":"boolean"}},"required":["projectId","package","reused"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/publishing/thumbnail":{"post":{"operationId":"studio_publishing_thumbnail","summary":"Draw a thumbnail (9:16, 1:1 or 16:9) with the film's characters and the package headline. Answers with a job.","description":"Draws a thumbnail for the film's current video from its publishing package (write the metadata first), using the film's character and place pictures as references, and puts the package headline on it. The picture maker is imageModel (default: the film's thumbnail or picture model). Priced per picture by the model and how many references are sent, settled to the provider's actual cost; the quote is the most it can cost (including a backup provider), and you are never charged more than the price you approved. A failed picture is refunded. Runs in the background. Refused while the film is open in the AutoClips app or anything else runs on it.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"studio.publishing.thumbnail","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"studio_publishing action=thumbnail","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ratio":{"description":"Thumbnail shapes: Which thumbnail shapes to make for the publishing package.\nChoices:\n- 9:16 — 9:16: A 9:16 thumbnail.\n- 1:1 — 1:1: A 1:1 thumbnail.\n- 16:9 — 16:9: A 16:9 thumbnail.","type":"string","enum":["9:16","1:1","16:9"]},"imageModel":{"description":"Picture maker: Which model draws the characters, places, objects and character sheets.\nChoices:\n- dream5 — Dream 5: Recommended for polished 3D character and asset references. (41 credits per picture)\n- gptImage2High — ChatGPT Image 2.0 High: Strong prompt accuracy and crisp production detail. (30 credits per picture)\n- nanoBanana2 — Nano Banana 2: Fast high-quality generations with flexible references. (72 credits per picture)\nDefault: the film's thumbnail picture maker, else its picture maker, else dream5 (leave it out).","type":"string","enum":["dream5","gptImage2High","nanoBanana2"]},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"required":["ratio"],"additionalProperties":false},"example":{"ratio":"9:16"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"started":{"description":"True when background work started; follow it with autoclips_jobs get.","type":"boolean"},"job":{"description":"The background work, when some started.","anyOf":[{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},{"type":"null"}]},"ratio":{"type":"string"},"imageModel":{"type":"string"},"packageId":{"type":"string"}},"required":["projectId","started","job","ratio","imageModel","packageId"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/references":{"post":{"operationId":"studio_references_attach","summary":"Add pictures from your media library as references for the project, a character, object, place or clip, or as an item's own picture.","description":"Adds pictures from your media library (autoclips_media) to the film. to says where: project: pictures the writer looks at when it writes the script (only before the script is written). character, object or place (id from studio_looks overview): as reference (default), pictures its next picture is drawn to match (up to 16); as picture, exactly one picture that becomes its picture and is used as it is, like dropping your own picture on its card in the app: nothing is drawn for it, and a character's sheet is made straight from it. To draw it from that picture, name it in prepare_pictures first (the app's \"Draw from it\"), then in make_pictures. clip (id from studio_projects get, include clips): up to 4 pictures the clip is sent with the next time it is made. The pictures are copied into Studio's own folder. Free; counts toward the daily limit for uploads. A reference on an item clears its written picture direction (it was written without it; prepare_pictures writes a new one before the item is next drawn, which costs credits). A picture of its own clears planned clips (the app does the same): send clearPlannedClips: true then. An AI app asks first in both cases. Refused while the project is open and saving in the app, and while anything runs on it. An app tab that had the project open before keeps these pictures unless the person changes the attached files there afterwards.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.references.attach","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_looks action=attach_pictures","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"description":"Where the pictures go: project, character, object, place or clip.","type":"string","enum":["project","character","object","place","clip"]},"id":{"description":"The character, object, place or clip id. Not for the project.","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_.:-]+$"},"mediaIds":{"description":"The pictures, from your media library (each once).","minItems":1,"maxItems":16,"type":"array","items":{"description":"A picture in your media library (autoclips_media list, upload_link or import_url).","type":"string","pattern":"^[a-fA-F0-9]{24}$"}},"as":{"description":"For a character, object or place: reference (default) steers its next picture; picture makes this one picture its picture, used as it is.","type":"string","enum":["reference","picture"]},"clearPlannedClips":{"description":"Required when the project already has planned clips: a new picture, sheet or voice clears them (they were planned with the old look and must be planned again, which costs credits). Finished videos stay.","type":"boolean","const":true}},"required":["to","mediaIds"],"additionalProperties":false},"example":{"to":"character","id":"character_mia","mediaIds":["66f7c0ffee00000000000001"]}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"to":{"type":"string"},"attached":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"}},"required":["id","name","url"],"additionalProperties":false}},"item":{"description":"The character, object or place as it is now.","anyOf":[{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["character","object","place"]},"name":{"type":"string"},"canHavePicture":{"description":"False for fixed furniture, which is drawn as part of its place.","type":"boolean"},"direction":{"description":"The picture direction make_pictures draws from: ready; missing (none yet); or outdated (written before Studio could see this item's reference pictures). A missing or outdated one is written by prepare_pictures before the item is drawn, as the app does; an item that already has its picture keeps its direction as it is until you name the item to draw it again.","type":"string","enum":["ready","missing","outdated"]},"picture":{"description":"The picture the film uses. source \"yours\": your own picture, used as it is: nothing is drawn for it. To draw it from that picture, name it in prepare_pictures first (the app's \"Draw from it\"), then in make_pictures.","anyOf":[{"type":"object","properties":{"url":{"type":"string"},"versionId":{"type":"string"},"source":{"type":"string","enum":["made","yours"]}},"required":["url","versionId","source"],"additionalProperties":{}},{"type":"null"}]},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"}},"required":["id","name","url"],"additionalProperties":{}}}},"required":["id","kind","name","canHavePicture","direction","picture","references"],"additionalProperties":{}},{"type":"null"}]},"directionCleared":{"type":"boolean"},"clipsCleared":{"type":"number"},"note":{"type":"string"}},"required":["projectId","to","attached","item","directionCleared","clipsCleared","note"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/rename":{"post":{"operationId":"studio_projects_rename","summary":"Give a Studio project a new name. Free.","description":"Renames the project (up to 80 characters). The app shows this name in its history list and keeps it: saving in the app no longer renames the project after its script. Refused while an app tab is editing the project (it saved in the last 90 seconds), and for a film shown as a public sample.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.projects.rename","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_projects action=rename","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"The project name (up to 80 characters), as it shows in the app's history list.","type":"string","minLength":1,"maxLength":80}},"required":["title"],"additionalProperties":false},"example":{"title":"Robot and the lost star"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from list or create).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"studio"},"title":{"description":"The film's name: the script's title once there is one, unless the project was given a name of its own. Until it is renamed, the app's history list may still show the first words of the idea.","type":"string"},"status":{"description":"How far the film got: new (Just an idea so far); brainstorming (Idea saved, no script yet); research_ready (Trend ideas found, no script yet); script_ready (Script written); film_ready (Film ready). film_ready while the project holds a finished video (video); stage says where the film is in more detail.","type":"string"},"stage":{"description":"Where the film is, in plain words: an open Autopilot run and its step, else \"Film ready\" with its length, else how many clips are made, else the status.","type":"string"},"mode":{"description":"director = made step by step; autopilot = Autopilot makes the whole film.","type":"string","enum":["director","autopilot"]},"step":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"settings":{"description":"The settings, in the same words create and update take.","type":"object","properties":{},"additionalProperties":{}},"idea":{"anyOf":[{"type":"string"},{"type":"null"}]},"counts":{"type":"object","properties":{},"additionalProperties":{}},"video":{"description":"The finished film, once there is one.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"autopilot":{"description":"The Autopilot run, when one was started.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"openInApp":{"description":"True while an app tab is editing the project (it saved in the last 90 seconds). The API cannot change it until that tab has been still for 90 seconds or is closed.","type":"boolean"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"app":{"type":"string"},"editor":{"type":"string"}},"required":["app","editor"],"additionalProperties":{}}},"required":["id","product","title","status","stage","mode","step","durationSeconds","settings","idea","counts","video","autopilot","openInApp","createdAt","updatedAt","links"],"additionalProperties":{}},"note":{"type":"string"}},"required":["project","note"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19","product":"studio","title":"Robot and the lost star","status":"brainstorming","stage":"Idea saved, no script yet","mode":"director","step":"script-analysis","durationSeconds":30,"settings":{"writerModel":"trendScout","webSearch":false,"aspectRatio":"9:16","quality":"1080p","nativeAudio":true,"imageModel":"dream5","inSceneText":true,"textOnTop":true,"whoSpeaks":"auto","musicSource":"studio","productionModel":"trendScout","enhanceBrief":true,"speed":1.1},"idea":"A tiny robot tries to return a lost star to the sky","counts":{"scenes":0,"characters":0,"assets":0,"clips":0,"clipsReady":0,"finalVideos":0},"video":null,"autopilot":null,"openInApp":false,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","links":{"app":"https://app.autoclips.app/studio-2?projectId=9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19","editor":"https://app.autoclips.app/editor/9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"}},"note":"The app shows this name in its history list and keeps it: saving in the app no longer renames the project after its script."}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/render":{"post":{"operationId":"studio_render_start","summary":"Render every clip still to make, one after another, then join the film. Paid (the most it can cost); a job.","description":"The app's \"Generate final video\", done by the server: it renders every planned clip that has no finished video yet, in order (each continues from the one before), composes the soundtrack when the film needs one (never when a track of your own or a popular track is picked), joins the clips into the film at its speed, and emails you when it finishes while nobody is watching. With a changeRequest it renders every clip again, each with that change. speed sets how fast the finished film plays (free; saved on the film, as the app's Speed row does); left out, the film's saved speed is used, which is 1.1x for a new film. A clip that fails is tried up to 3 times (each failed try is refunded); a clip the video model refuses stops the render, and what was made stays. A clip written before one of its pictures was re-made is refused up front: catch it up first (catch_up, free). Paid: the quote is the most it can cost, and each clip is charged as it starts. It answers with a job at once: follow it with autoclips_jobs get (checking it also moves the render along). stop_render stops it after the clip being made now. Refused while the film is open in the app or anything else runs on it.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"studio.render.start","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"studio_clips action=render_all","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"changeRequest":{"description":"Render every clip again with this change, in plain words (up to 3,000 characters). Leave out to render only the clips still to make.","type":"string","minLength":3,"maxLength":3000},"speed":{"description":"Final video speed: How fast the finished video plays. Every clip plays faster with its voices at their own pitch; the soundtrack and the outro stay at normal speed. A finished video lasts its clips' seconds divided by the speed. Free: clips are priced by the seconds rendered, which the speed does not change. A film joined before speeds existed stays at 1x until a speed is chosen.\nChoices:\n- 1 — 1x: Normal speed, as the clips were rendered. (Free)\n- 1.1 — 1.1x: A little quicker than rendered. What a new film plays at. (Free)\n- 1.25 — 1.25x: Recommended: the quick pace short-form edits use. (Free)\n- 1.5 — 1.5x: 1.5 times as fast as rendered. (Free)\n- 2 — 2x: 2 times as fast as rendered. (Free)\nDefault: The film's saved speed; a new film plays at 1.1x (leave it out).\nSend the value as text (\"1.25\") or a number (1.25).","anyOf":[{"description":"Final video speed: How fast the finished video plays. Every clip plays faster with its voices at their own pitch; the soundtrack and the outro stay at normal speed. A finished video lasts its clips' seconds divided by the speed. Free: clips are priced by the seconds rendered, which the speed does not change. A film joined before speeds existed stays at 1x until a speed is chosen.\nChoices:\n- 1 — 1x: Normal speed, as the clips were rendered. (Free)\n- 1.1 — 1.1x: A little quicker than rendered. What a new film plays at. (Free)\n- 1.25 — 1.25x: Recommended: the quick pace short-form edits use. (Free)\n- 1.5 — 1.5x: 1.5 times as fast as rendered. (Free)\n- 2 — 2x: 2 times as fast as rendered. (Free)\nDefault: The film's saved speed; a new film plays at 1.1x (leave it out).","type":"string","enum":["1","2","1.1","1.25","1.5"]},{"type":"number","enum":[1,1.1,1.25,1.5,2]}]},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"job":{"description":"Follow it with autoclips_jobs get; it succeeds with result.videoUrl once the film is joined.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"clipsToRender":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"soundtrack":{"description":"True when a new soundtrack take will be composed.","type":"boolean"},"speed":{"description":"How fast the finished film will play (1 is normal speed).","type":"number"},"approvedCredits":{"description":"The most it can cost; each clip is charged as it starts.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["projectId","job","clipsToRender","soundtrack","speed","approvedCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19","job":{"id":"job_0192a3b4c5d6e7f8a9b0c1d2","product":"studio","kind":"studio.final_render","resource":{"type":"project","id":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},"status":"running","step":"Starting the first clip","progress":null,"result":null,"error":null,"createdAt":"2026-09-29T10:00:00.000Z","updatedAt":"2026-09-29T10:00:00.000Z","finishedAt":null,"poll_after_seconds":30},"clipsToRender":3,"soundtrack":true,"speed":1.1,"approvedCredits":4920}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/render/stop":{"post":{"operationId":"studio_render_cancel","summary":"Stop render_all after the clip being made now. Free.","description":"Stops the server's render of the film: no further clip starts and the film is not joined. The clip being made right now still finishes and is charged; clips already made stay, and render_all later carries on from where it stopped. If the film is open in the app and that tab is rendering, stop it there too.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.render.cancel","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_clips action=stop_render","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"stopped":{"type":"boolean","const":true},"clipStillRendering":{"type":"boolean"},"message":{"type":"string"}},"required":["projectId","stopped","clipStillRendering","message"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/review":{"get":{"operationId":"studio_review_get","summary":"What the free check for mistakes flagged in each clip of the film, and what fixing each costs.","description":"Reads the film's Review: for every clip of the film (the videos it uses now), whether the free check ran, its shots, and every flag: what is wrong, where (seconds in the clip, on its cuts), what a fix changes, its status, and what fixing it would render and cost. A clip made by a fix shows the flags of the clip it fixed until the film is joined again. Free. A fix that failed while nobody was watching is marked failed here, as the app does, so it can be fixed again.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"studio.review.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_review action=get","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"summary":{"type":"object","properties":{"status":{"description":"checking (a clip is being checked), failed (a check failed: start it again, free), none (not checked yet: start it, free), ready.","type":"string","enum":["checking","failed","none","ready"]},"toFix":{"description":"Open flags a viewer will see (the app's \"N to fix\").","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"notice":{"description":"Open flags worth a look.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"script":{"description":"Open flags that only differ from the script.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fixing":{"description":"Flags being fixed or checked after a fix.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fixed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["status","toFix","notice","script","fixing","fixed"],"additionalProperties":false},"needsJoin":{"description":"True when a clip uses a fixed video the film was not joined with yet: join it again with studio_clips stitch (free) to put the fixes into the video.","type":"boolean"},"clips":{"type":"array","items":{"type":"object","properties":{"clipId":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"title":{"type":"string"},"version":{"anyOf":[{"type":"object","properties":{"id":{"description":"The clip video the check is about (the one the film uses).","type":"string"},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fromFix":{"description":"True when this video came from a fix.","type":"boolean"},"fixedVersionId":{"description":"The clip video it fixed.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","videoUrl","fromFix","fixedVersionId"],"additionalProperties":false},{"type":"null"}]},"busy":{"description":"The clip is being made right now (a render or a fix).","type":"boolean"},"check":{"type":"object","properties":{"status":{"description":"checking, checked, failed (start it again, free), not_checked (start it, free), or no_video (the clip is not made yet).","type":"string","enum":["checking","checked","failed","not_checked","no_video"]},"kind":{"description":"fix-check: this video came from a fix; it carries the flags of the video it fixed, and only the fixed seconds are checked again.","type":"string","enum":["check","fix-check"]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","kind","message"],"additionalProperties":false},"shots":{"description":"The clip's shots as the check measured them (its hard cuts), with a picture of each.","type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"start":{"type":"number"},"end":{"type":"number"},"pictureUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["number","start","end","pictureUrl"],"additionalProperties":false}},"flags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"group":{"description":"fix: a viewer will see it; notice: worth a look; script: only differs from the script (a viewer would not notice).","type":"string","enum":["fix","notice","script"]},"severity":{"type":"string","enum":["high","medium","low"]},"status":{"description":"open; dismissed (marked as looking fine); fixing (a fix is rendering); checking (fixed, the new seconds are being checked); fixed; still_off (the check says it is still there); failed (the fix could not render: fix it again, or reword it first; while that fix's bill is being checked there is no fix, and noFix says so).","type":"string","enum":["open","dismissed","fixing","checking","fixed","still_off","failed"]},"start":{"description":"Where it starts in the clip, in seconds (on a cut).","type":"number"},"end":{"description":"Where it ends in the clip, in seconds.","type":"number"},"shots":{"description":"The clip's shots it is on (1 = the first).","type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"title":{"type":"string"},"what":{"description":"What is wrong.","type":"string"},"fix":{"description":"What a fix changes: the words the fix is rendered with (change them with flag reword).","type":"string"},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"markedBy":{"description":"check: the free check flagged it; you: you marked it (flag add).","type":"string","enum":["check","you"]},"newSound":{"description":"True when a face on camera speaks in it, so a fix makes new sound there; otherwise a fix keeps the clip's sound.","type":"boolean"},"textOnly":{"description":"Only small writing on a screen is off (no fix: a re-render makes new writing up).","type":"boolean"},"fixJobId":{"description":"While a fix renders: its clip render (studio_clips get_job).","anyOf":[{"type":"string"},{"type":"null"}]},"fixOffer":{"description":"What fixing it renders and costs (fix); null when it has no fix right now.","anyOf":[{"type":"object","properties":{"credits":{"description":"The most this fix can cost (what it asks you to approve).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"chargedAtStart":{"description":"Taken when it starts (the list price; at most this when exact is false); settled when it is made, and given back if it fails.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"renderSeconds":{"description":"Seconds the video model renders (4 to 8).","type":"number"},"keepSeconds":{"description":"Seconds of the clip it replaces: the flagged shots.","type":"number"},"start":{"description":"Where the replaced stretch starts in the clip, in seconds.","type":"number"},"end":{"description":"Where it ends.","type":"number"},"alsoFixes":{"description":"Other open flags on the same seconds or the shot right next to them: the same render fixes them, for the same price.","type":"array","items":{"type":"string"}},"exact":{"description":"False when this clip version came from a fix and its cuts were not measured yet: priced as the longest fix (8 seconds). Join the film again (studio_clips stitch, free) for the exact price.","type":"boolean"}},"required":["credits","chargedAtStart","renderSeconds","keepSeconds","start","end","alsoFixes","exact"],"additionalProperties":false},{"type":"null"}]},"noFix":{"description":"Why it has no fix, when it is open but cannot be fixed, or not yet (while its clip's last start is having its bill checked).","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","group","severity","status","start","end","shots","title","what","fix","category","markedBy","newSound","textOnly","fixJobId","fixOffer","noFix"],"additionalProperties":false}}},"required":["clipId","number","title","version","busy","check","shots","flags"],"additionalProperties":false}},"next":{"description":"What to do next, in plain words.","type":"string"}},"required":["projectId","summary","needsJoin","clips","next"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"studio_review_start","summary":"Check the film's clips for mistakes: the ones not checked yet, or whose check failed. Free.","description":"Starts the free check of every clip of the film that has a video and was not checked yet, whose check failed, or that came from a fix. A clip already checked is never checked again. The check runs in the background (a minute or two, two clips at a time): read the result with get. Every join (studio_clips stitch or render_all) starts it on its own, so this is for a film joined before Review existed, or a check that failed. Free; counts toward the daily limit for free AI helpers only when a clip is checked.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.review.start","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_review action=start","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"summary":{"type":"object","properties":{"status":{"description":"checking (a clip is being checked), failed (a check failed: start it again, free), none (not checked yet: start it, free), ready.","type":"string","enum":["checking","failed","none","ready"]},"toFix":{"description":"Open flags a viewer will see (the app's \"N to fix\").","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"notice":{"description":"Open flags worth a look.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"script":{"description":"Open flags that only differ from the script.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fixing":{"description":"Flags being fixed or checked after a fix.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fixed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["status","toFix","notice","script","fixing","fixed"],"additionalProperties":false},"needsJoin":{"description":"True when a clip uses a fixed video the film was not joined with yet: join it again with studio_clips stitch (free) to put the fixes into the video.","type":"boolean"},"clips":{"type":"array","items":{"type":"object","properties":{"clipId":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"title":{"type":"string"},"version":{"anyOf":[{"type":"object","properties":{"id":{"description":"The clip video the check is about (the one the film uses).","type":"string"},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fromFix":{"description":"True when this video came from a fix.","type":"boolean"},"fixedVersionId":{"description":"The clip video it fixed.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","videoUrl","fromFix","fixedVersionId"],"additionalProperties":false},{"type":"null"}]},"busy":{"description":"The clip is being made right now (a render or a fix).","type":"boolean"},"check":{"type":"object","properties":{"status":{"description":"checking, checked, failed (start it again, free), not_checked (start it, free), or no_video (the clip is not made yet).","type":"string","enum":["checking","checked","failed","not_checked","no_video"]},"kind":{"description":"fix-check: this video came from a fix; it carries the flags of the video it fixed, and only the fixed seconds are checked again.","type":"string","enum":["check","fix-check"]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","kind","message"],"additionalProperties":false},"shots":{"description":"The clip's shots as the check measured them (its hard cuts), with a picture of each.","type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"start":{"type":"number"},"end":{"type":"number"},"pictureUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["number","start","end","pictureUrl"],"additionalProperties":false}},"flags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"group":{"description":"fix: a viewer will see it; notice: worth a look; script: only differs from the script (a viewer would not notice).","type":"string","enum":["fix","notice","script"]},"severity":{"type":"string","enum":["high","medium","low"]},"status":{"description":"open; dismissed (marked as looking fine); fixing (a fix is rendering); checking (fixed, the new seconds are being checked); fixed; still_off (the check says it is still there); failed (the fix could not render: fix it again, or reword it first; while that fix's bill is being checked there is no fix, and noFix says so).","type":"string","enum":["open","dismissed","fixing","checking","fixed","still_off","failed"]},"start":{"description":"Where it starts in the clip, in seconds (on a cut).","type":"number"},"end":{"description":"Where it ends in the clip, in seconds.","type":"number"},"shots":{"description":"The clip's shots it is on (1 = the first).","type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"title":{"type":"string"},"what":{"description":"What is wrong.","type":"string"},"fix":{"description":"What a fix changes: the words the fix is rendered with (change them with flag reword).","type":"string"},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"markedBy":{"description":"check: the free check flagged it; you: you marked it (flag add).","type":"string","enum":["check","you"]},"newSound":{"description":"True when a face on camera speaks in it, so a fix makes new sound there; otherwise a fix keeps the clip's sound.","type":"boolean"},"textOnly":{"description":"Only small writing on a screen is off (no fix: a re-render makes new writing up).","type":"boolean"},"fixJobId":{"description":"While a fix renders: its clip render (studio_clips get_job).","anyOf":[{"type":"string"},{"type":"null"}]},"fixOffer":{"description":"What fixing it renders and costs (fix); null when it has no fix right now.","anyOf":[{"type":"object","properties":{"credits":{"description":"The most this fix can cost (what it asks you to approve).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"chargedAtStart":{"description":"Taken when it starts (the list price; at most this when exact is false); settled when it is made, and given back if it fails.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"renderSeconds":{"description":"Seconds the video model renders (4 to 8).","type":"number"},"keepSeconds":{"description":"Seconds of the clip it replaces: the flagged shots.","type":"number"},"start":{"description":"Where the replaced stretch starts in the clip, in seconds.","type":"number"},"end":{"description":"Where it ends.","type":"number"},"alsoFixes":{"description":"Other open flags on the same seconds or the shot right next to them: the same render fixes them, for the same price.","type":"array","items":{"type":"string"}},"exact":{"description":"False when this clip version came from a fix and its cuts were not measured yet: priced as the longest fix (8 seconds). Join the film again (studio_clips stitch, free) for the exact price.","type":"boolean"}},"required":["credits","chargedAtStart","renderSeconds","keepSeconds","start","end","alsoFixes","exact"],"additionalProperties":false},{"type":"null"}]},"noFix":{"description":"Why it has no fix, when it is open but cannot be fixed, or not yet (while its clip's last start is having its bill checked).","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","group","severity","status","start","end","shots","title","what","fix","category","markedBy","newSound","textOnly","fixJobId","fixOffer","noFix"],"additionalProperties":false}}},"required":["clipId","number","title","version","busy","check","shots","flags"],"additionalProperties":false}},"next":{"description":"What to do next, in plain words.","type":"string"},"started":{"description":"Clips whose check started now.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["projectId","summary","needsJoin","clips","next","started"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/review/fixes":{"post":{"operationId":"studio_review_fix","summary":"Fix one flagged moment: re-render only its seconds and splice them into the clip. Paid; answers with a job.","description":"Re-renders only the shots of one flag (4 to 8 seconds of video, with the clip's pictures, rendered on from the seconds before it) with the flag's fix words, and splices them back into the clip; everything else in the clip stays frame for frame. Any other open flag on the same seconds, or on the shot right next to them, is fixed in the same render for the same price (fixOffer.alsoFixes in get), as in the app. Paid like a clip of that length; the quote is the most it can cost, and a fix that fails is given back. One fix at a time per clip; fixes on different clips can run side by side. It answers with a job: when it succeeds, the clip uses the fixed video; join the film again with studio_clips stitch (free) to put it into the video, which also checks the fixed seconds (free). Refused for a flag that only differs from the script, one on small writing (a re-render makes new writing up), or one longer than 8 seconds (render the clip again instead), while the clip's last start is having its bill checked, and while the film is open in the AutoClips app or anything else runs on it.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"studio.review.fix","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"studio_review action=fix","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clipId":{"description":"One clip of the film: its clipId from studio_review get.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"flagId":{"description":"A flag of that clip: its id from studio_review get.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"versionId":{"description":"Optional safety: the clip video you read (clips[].version.id from get). If the clip changed since, nothing is done.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"required":["clipId","flagId"],"additionalProperties":false},"example":{"clipId":"segment-2","flagId":"f1"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"clipId":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fixes":{"description":"The flags this render fixes: the one you named first.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false}},"start":{"description":"Where the replaced stretch starts in the clip, in seconds.","type":"number"},"end":{"type":"number"},"renderSeconds":{"type":"number"},"clipJobId":{"description":"The fix's clip render (studio_clips get_job); the clip's new video id once it is made.","type":"string"},"job":{"description":"Follow it with autoclips_jobs get. When it succeeds, join the film again with studio_clips stitch (free).","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"creditsCharged":{"description":"Taken now (the list price); the final bill is in the job's result.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["projectId","clipId","number","fixes","start","end","renderSeconds","clipJobId","job","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/review/flags":{"post":{"operationId":"studio_review_flag","summary":"Your word on a flag: looks_fine, restore, reword what the fix changes, or add a moment yourself. Free.","description":"Changes the review of one clip, as the Review step does. looks_fine marks an open flag as fine (it leaves the count to fix); restore puts a flag marked as fine back; reword changes what its fix changes (fix: the new words; the next fix renders with them); add marks a moment yourself (what is wrong, from and to in seconds of the clip; it grows to whole shots) as a flag to fix. Works on a clip whose check finished (check.status checked). Free; nothing renders.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.review.flag","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_review action=flag","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clipId":{"description":"One clip of the film: its clipId from studio_review get.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"change":{"description":"looks_fine (an open flag is fine), restore (undo looks_fine), reword (change what the fix changes; send fix), or add (mark a moment yourself; send what, from and to).","type":"string","enum":["looks_fine","restore","reword","add"]},"flagId":{"description":"The flag to change (looks_fine, restore, reword).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"fix":{"description":"reword: what the fix should change, in plain words (up to 1500 characters).","type":"string","minLength":3,"maxLength":1500},"what":{"description":"add: what is wrong in this moment (up to 600 characters); a fix renders with these words.","type":"string","minLength":3,"maxLength":600},"from":{"description":"add: where the moment starts, in seconds of the clip (0 = its start). It grows to the whole shots it touches.","type":"number","minimum":0,"maximum":600},"to":{"description":"add: where it ends, in seconds of the clip (default: from, the one shot there).","type":"number","minimum":0,"maximum":600},"newSound":{"description":"add: true when a face on camera speaks in this moment, so its fix makes new sound; default false keeps the clip's sound.","type":"boolean"},"versionId":{"description":"Optional safety: the clip video you read (clips[].version.id from get). If the clip changed since, nothing is done.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"required":["clipId","change"],"additionalProperties":false},"example":{"clipId":"segment-2","change":"looks_fine","flagId":"f3"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"clipId":{"type":"string"},"change":{"type":"string","enum":["looks_fine","restore","reword","add"]},"flag":{"description":"The flag as it is now.","type":"object","properties":{"id":{"type":"string"},"group":{"description":"fix: a viewer will see it; notice: worth a look; script: only differs from the script (a viewer would not notice).","type":"string","enum":["fix","notice","script"]},"severity":{"type":"string","enum":["high","medium","low"]},"status":{"description":"open; dismissed (marked as looking fine); fixing (a fix is rendering); checking (fixed, the new seconds are being checked); fixed; still_off (the check says it is still there); failed (the fix could not render: fix it again, or reword it first; while that fix's bill is being checked there is no fix, and noFix says so).","type":"string","enum":["open","dismissed","fixing","checking","fixed","still_off","failed"]},"start":{"description":"Where it starts in the clip, in seconds (on a cut).","type":"number"},"end":{"description":"Where it ends in the clip, in seconds.","type":"number"},"shots":{"description":"The clip's shots it is on (1 = the first).","type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"title":{"type":"string"},"what":{"description":"What is wrong.","type":"string"},"fix":{"description":"What a fix changes: the words the fix is rendered with (change them with flag reword).","type":"string"},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"markedBy":{"description":"check: the free check flagged it; you: you marked it (flag add).","type":"string","enum":["check","you"]},"newSound":{"description":"True when a face on camera speaks in it, so a fix makes new sound there; otherwise a fix keeps the clip's sound.","type":"boolean"},"textOnly":{"description":"Only small writing on a screen is off (no fix: a re-render makes new writing up).","type":"boolean"},"fixJobId":{"description":"While a fix renders: its clip render (studio_clips get_job).","anyOf":[{"type":"string"},{"type":"null"}]},"fixOffer":{"description":"What fixing it renders and costs (fix); null when it has no fix right now.","anyOf":[{"type":"object","properties":{"credits":{"description":"The most this fix can cost (what it asks you to approve).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"chargedAtStart":{"description":"Taken when it starts (the list price; at most this when exact is false); settled when it is made, and given back if it fails.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"renderSeconds":{"description":"Seconds the video model renders (4 to 8).","type":"number"},"keepSeconds":{"description":"Seconds of the clip it replaces: the flagged shots.","type":"number"},"start":{"description":"Where the replaced stretch starts in the clip, in seconds.","type":"number"},"end":{"description":"Where it ends.","type":"number"},"alsoFixes":{"description":"Other open flags on the same seconds or the shot right next to them: the same render fixes them, for the same price.","type":"array","items":{"type":"string"}},"exact":{"description":"False when this clip version came from a fix and its cuts were not measured yet: priced as the longest fix (8 seconds). Join the film again (studio_clips stitch, free) for the exact price.","type":"boolean"}},"required":["credits","chargedAtStart","renderSeconds","keepSeconds","start","end","alsoFixes","exact"],"additionalProperties":false},{"type":"null"}]},"noFix":{"description":"Why it has no fix, when it is open but cannot be fixed, or not yet (while its clip's last start is having its bill checked).","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","group","severity","status","start","end","shots","title","what","fix","category","markedBy","newSound","textOnly","fixJobId","fixOffer","noFix"],"additionalProperties":false},"clip":{"description":"The clip's review as it is now.","type":"object","properties":{"clipId":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"title":{"type":"string"},"version":{"anyOf":[{"type":"object","properties":{"id":{"description":"The clip video the check is about (the one the film uses).","type":"string"},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fromFix":{"description":"True when this video came from a fix.","type":"boolean"},"fixedVersionId":{"description":"The clip video it fixed.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","videoUrl","fromFix","fixedVersionId"],"additionalProperties":false},{"type":"null"}]},"busy":{"description":"The clip is being made right now (a render or a fix).","type":"boolean"},"check":{"type":"object","properties":{"status":{"description":"checking, checked, failed (start it again, free), not_checked (start it, free), or no_video (the clip is not made yet).","type":"string","enum":["checking","checked","failed","not_checked","no_video"]},"kind":{"description":"fix-check: this video came from a fix; it carries the flags of the video it fixed, and only the fixed seconds are checked again.","type":"string","enum":["check","fix-check"]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","kind","message"],"additionalProperties":false},"shots":{"description":"The clip's shots as the check measured them (its hard cuts), with a picture of each.","type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"start":{"type":"number"},"end":{"type":"number"},"pictureUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["number","start","end","pictureUrl"],"additionalProperties":false}},"flags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"group":{"description":"fix: a viewer will see it; notice: worth a look; script: only differs from the script (a viewer would not notice).","type":"string","enum":["fix","notice","script"]},"severity":{"type":"string","enum":["high","medium","low"]},"status":{"description":"open; dismissed (marked as looking fine); fixing (a fix is rendering); checking (fixed, the new seconds are being checked); fixed; still_off (the check says it is still there); failed (the fix could not render: fix it again, or reword it first; while that fix's bill is being checked there is no fix, and noFix says so).","type":"string","enum":["open","dismissed","fixing","checking","fixed","still_off","failed"]},"start":{"description":"Where it starts in the clip, in seconds (on a cut).","type":"number"},"end":{"description":"Where it ends in the clip, in seconds.","type":"number"},"shots":{"description":"The clip's shots it is on (1 = the first).","type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"title":{"type":"string"},"what":{"description":"What is wrong.","type":"string"},"fix":{"description":"What a fix changes: the words the fix is rendered with (change them with flag reword).","type":"string"},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"markedBy":{"description":"check: the free check flagged it; you: you marked it (flag add).","type":"string","enum":["check","you"]},"newSound":{"description":"True when a face on camera speaks in it, so a fix makes new sound there; otherwise a fix keeps the clip's sound.","type":"boolean"},"textOnly":{"description":"Only small writing on a screen is off (no fix: a re-render makes new writing up).","type":"boolean"},"fixJobId":{"description":"While a fix renders: its clip render (studio_clips get_job).","anyOf":[{"type":"string"},{"type":"null"}]},"fixOffer":{"description":"What fixing it renders and costs (fix); null when it has no fix right now.","anyOf":[{"type":"object","properties":{"credits":{"description":"The most this fix can cost (what it asks you to approve).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"chargedAtStart":{"description":"Taken when it starts (the list price; at most this when exact is false); settled when it is made, and given back if it fails.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"renderSeconds":{"description":"Seconds the video model renders (4 to 8).","type":"number"},"keepSeconds":{"description":"Seconds of the clip it replaces: the flagged shots.","type":"number"},"start":{"description":"Where the replaced stretch starts in the clip, in seconds.","type":"number"},"end":{"description":"Where it ends.","type":"number"},"alsoFixes":{"description":"Other open flags on the same seconds or the shot right next to them: the same render fixes them, for the same price.","type":"array","items":{"type":"string"}},"exact":{"description":"False when this clip version came from a fix and its cuts were not measured yet: priced as the longest fix (8 seconds). Join the film again (studio_clips stitch, free) for the exact price.","type":"boolean"}},"required":["credits","chargedAtStart","renderSeconds","keepSeconds","start","end","alsoFixes","exact"],"additionalProperties":false},{"type":"null"}]},"noFix":{"description":"Why it has no fix, when it is open but cannot be fixed, or not yet (while its clip's last start is having its bill checked).","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","group","severity","status","start","end","shots","title","what","fix","category","markedBy","newSound","textOnly","fixJobId","fixOffer","noFix"],"additionalProperties":false}}},"required":["clipId","number","title","version","busy","check","shots","flags"],"additionalProperties":false}},"required":["projectId","clipId","change","flag","clip"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/script":{"get":{"operationId":"studio_script_get","summary":"The script: scenes with every line and who says it, the action, the cast and the places, plus its revision.","description":"Reads the project's script as it is saved: title, scenes (each with its place, what the camera sees and every spoken line in order, with who says it), the characters, places and objects with their pictures, and the revision to send with an edit. includeText adds the whole script text. state says whether lines can still change here, whether a script is being written, and how many edits undo can take back. Never includes the directions sent to the video or picture makers.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"studio.script.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_script action=get","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects list or create).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"includeText","in":"query","required":false,"schema":{"description":"Also return the whole script text (as the app's script box shows it). Default false.","type":"boolean"},"description":"Also return the whole script text (as the app's script box shows it). Default false.","example":true}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"revision":{"description":"The script revision (null when there is no script). Send it as expectedRevision with an edit or undo.","anyOf":[{"type":"string"},{"type":"null"}]},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"hook":{"anyOf":[{"type":"string"},{"type":"null"}]},"storyMode":{"description":"Who speaks: mixed (the writer decides per scene: narrator, characters or both), narrated (only a narrator), dialogue (only characters), wordless (nobody).","type":"string","enum":["mixed","narrated","dialogue","wordless"]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"words":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"wordsPerSecond":{"type":"number"},"pacing":{"type":"string"},"planStale":{"description":"True after the text was edited (set_text) and before it was re-read (reanalyze): the scenes do not follow the text yet.","type":"boolean"},"narrator":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"character":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","character"],"additionalProperties":false},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"words":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pacing":{"description":"comfortable, too-fast (more words than the seconds can hold) or not-applicable.","type":"string"},"location":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},{"type":"null"}]},"action":{"description":"What the camera sees.","type":"string"},"lines":{"description":"Every spoken line, in the order it is said.","type":"array","items":{"type":"object","properties":{"line":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"speaker":{"description":"\"narrator\", or the id of the character who says it.","type":"string"},"speakerName":{"type":"string"},"text":{"type":"string"}},"required":["line","speaker","speakerName","text"],"additionalProperties":false}},"onScreenText":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["number","durationSeconds","words","pacing","location","action","lines","onScreenText"],"additionalProperties":false}},"characters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"scenes":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"pictureUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","description","scenes","pictureUrl"],"additionalProperties":{}}},"locations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"scenes":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"pictureUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","description","scenes","pictureUrl"],"additionalProperties":{}}},"objects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"scenes":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"pictureUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","description","scenes","pictureUrl"],"additionalProperties":{}}},"text":{"description":"The whole script text (with includeText).","type":"string"}},"required":["title","logline","hook","storyMode","durationSeconds","words","wordsPerSecond","pacing","planStale","narrator","scenes","characters","locations","objects"],"additionalProperties":false},{"type":"null"}]},"state":{"type":"object","properties":{"clipsPlanned":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"finishedVideos":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linesLocked":{"description":"True once clips are planned or a film is made: then only the title changes here, and lines change on their clip in the app.","type":"boolean"},"writing":{"description":"A script being written right now (by the API, with its job, or in the app).","anyOf":[{"type":"object","properties":{"jobId":{"anyOf":[{"type":"string"},{"type":"null"}]},"mode":{"anyOf":[{"type":"string","enum":["write","reanalyze"]},{"type":"null"}]}},"required":["jobId","mode"],"additionalProperties":false},{"type":"null"}]},"openInApp":{"description":"True while an app tab is editing the project (it saved in the last 90 seconds): changes wait until it has been still for 90 seconds or is closed.","type":"boolean"},"undoAvailable":{"description":"How many edits undo can take back.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["clipsPlanned","finishedVideos","linesLocked","writing","openInApp","undoAvailable"],"additionalProperties":false}},"required":["projectId","revision","script","state"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"projectId":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e","revision":"sr_4f1c9a2b7d3e8a60","script":{"title":"The Last Lighthouse","logline":"A keeper finds the lamp lit by someone who should not be there.","hook":"Nobody had climbed those stairs in forty years.","storyMode":"mixed","durationSeconds":20,"words":41,"wordsPerSecond":2.05,"pacing":"comfortable","planStale":false,"narrator":{"name":"Narrator","character":null},"scenes":[{"number":1,"durationSeconds":5,"words":8,"pacing":"comfortable","location":{"id":"location_lighthouse","name":"Lighthouse stairs"},"action":"Mia climbs the dark spiral stairs with a lantern.","lines":[{"line":1,"speaker":"narrator","speakerName":"Narrator","text":"Nobody had climbed those stairs in forty years."}],"onScreenText":"The Last Lighthouse"},{"number":2,"durationSeconds":5,"words":6,"pacing":"comfortable","location":{"id":"location_lighthouse","name":"Lighthouse stairs"},"action":"At the top the great lamp turns by itself.","lines":[{"line":1,"speaker":"character_mia","speakerName":"Mia","text":"Who lit you?"},{"line":2,"speaker":"character_tom","speakerName":"Tom","text":"I did."}],"onScreenText":null}],"characters":[{"id":"character_mia","name":"Mia","description":"A young keeper in a yellow raincoat.","scenes":[1,2],"pictureUrl":null,"role":"Hero","speaking":true,"sheetUrl":null},{"id":"character_tom","name":"Tom","description":"An old keeper with a white beard.","scenes":[2],"pictureUrl":null,"role":"Mystery","speaking":true,"sheetUrl":null}],"locations":[{"id":"location_lighthouse","name":"Lighthouse stairs","description":"A stone spiral staircase lit by one lantern.","scenes":[1,2],"pictureUrl":null}],"objects":[]},"state":{"clipsPlanned":0,"finishedVideos":0,"linesLocked":false,"writing":null,"openInApp":false,"undoAvailable":0}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"studio_script_edit","summary":"Change the script: lines and who says them, a scene's action or place, the title, names and descriptions, or the text.","description":"Applies up to 20 changes in order, all or nothing, as one new revision. Free. set_line / add_line / remove_line change a scene's spoken lines (a line's speaker is \"narrator\" or a character id); set_action and set_location change what happens and where. They follow the app's own clip rules: at most 4 characters speak in a scene, the narrator speaks before or after the characters (never between), and a scene holds only the words its seconds can say (about 3.2 a second). The full script text, word counts and voice plan follow automatically. update_character / update_location rename (the new name replaces the old one everywhere the story says it; the answer lists every line, action sentence and on-screen text that changed, since a name can also be an ordinary word: put a wrong one right with set_line or set_action, or undo) or re-describe (the next picture follows the new words). set_title changes the title. set_text replaces the whole script text, as typing in the app does; the scenes then need a re-read (reanalyze, paid) before lines can change here again. expectedRevision is required: the revision from get. If the script changed since (here, in the app or by Studio), nothing is saved and the answer is revision_conflict: read it again and redo the change. Once clips are planned or a film exists, only the title changes here: change a clip's lines on that clip in the app. Refused while an app tab is editing the project and while anything runs on it. An app tab that had the project open before keeps the new words, unless Studio changes the same part of the script first (for example a new picture of that character); reload such tabs.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.script.edit","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_script action=edit","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedRevision":{"description":"The script revision you read (studio_script get, revision). A stale batch is refused instead of changing the wrong lines.","type":"string","pattern":"^sr_[0-9a-f]{16}$"},"operations":{"description":"Up to 20 changes, applied in order: set_line, add_line, remove_line, set_action, set_location, set_title, set_text, update_character, update_location.","minItems":1,"maxItems":20,"type":"array","items":{"anyOf":[{"description":"Change one line: its words, who says it, or both.","type":"object","properties":{"op":{"type":"string","const":"set_line"},"scene":{"description":"A scene number from studio_script get (1 = the first scene).","type":"integer","minimum":1,"maximum":24},"line":{"description":"A line number within the scene, as studio_script get lists them (1 = the first). Line numbers count the lines as they are at that point of the batch.","type":"integer","minimum":1,"maximum":13},"text":{"description":"The exact words said, written the way they are spoken (up to 3000 characters for a character, 5000 for the narrator).","type":"string","minLength":1,"maxLength":5000},"speaker":{"description":"Who says it: \"narrator\" for the narrator's voice-over, or a character id from studio_script get (characters[].id). A narrated film has only the narrator; a character film has no narrator; a wordless film has no lines.","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_.:-]+$"}},"required":["op","scene","line"],"additionalProperties":false},{"description":"Add a line to a scene.","type":"object","properties":{"op":{"type":"string","const":"add_line"},"scene":{"description":"A scene number from studio_script get (1 = the first scene).","type":"integer","minimum":1,"maximum":24},"speaker":{"description":"Who says it: \"narrator\" for the narrator's voice-over, or a character id from studio_script get (characters[].id). A narrated film has only the narrator; a character film has no narrator; a wordless film has no lines.","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_.:-]+$"},"text":{"description":"The exact words said, written the way they are spoken (up to 3000 characters for a character, 5000 for the narrator).","type":"string","minLength":1,"maxLength":5000},"position":{"description":"The line number the new line gets (1 = first). Default: after the last line.","type":"integer","minimum":1,"maximum":12}},"required":["op","scene","speaker","text"],"additionalProperties":false},{"description":"Remove one line from a scene.","type":"object","properties":{"op":{"type":"string","const":"remove_line"},"scene":{"description":"A scene number from studio_script get (1 = the first scene).","type":"integer","minimum":1,"maximum":24},"line":{"description":"A line number within the scene, as studio_script get lists them (1 = the first). Line numbers count the lines as they are at that point of the batch.","type":"integer","minimum":1,"maximum":13}},"required":["op","scene","line"],"additionalProperties":false},{"description":"Change what happens in a scene.","type":"object","properties":{"op":{"type":"string","const":"set_action"},"scene":{"description":"A scene number from studio_script get (1 = the first scene).","type":"integer","minimum":1,"maximum":24},"text":{"description":"What the camera sees in the scene: who does what, where, with which prop, and how it ends (up to 5,000 characters).","type":"string","minLength":1,"maxLength":5000}},"required":["op","scene","text"],"additionalProperties":false},{"description":"Move a scene to another of the script's places.","type":"object","properties":{"op":{"type":"string","const":"set_location"},"scene":{"description":"A scene number from studio_script get (1 = the first scene).","type":"integer","minimum":1,"maximum":24},"locationId":{"description":"A place id from studio_script get (locations[].id).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"required":["op","scene","locationId"],"additionalProperties":false},{"description":"Change the film's title.","type":"object","properties":{"op":{"type":"string","const":"set_title"},"title":{"description":"The film's title in its script (up to 180 characters). The project's name in the app's history list is separate: studio_projects rename.","type":"string","minLength":1,"maxLength":180}},"required":["op","title"],"additionalProperties":false},{"description":"Replace the whole script text, as typing in the app's script box does. The scenes then need a re-read (studio_script reanalyze, paid) before anything else is made.","type":"object","properties":{"op":{"type":"string","const":"set_text"},"text":{"description":"The whole script text, as the app's script box shows it (up to 30,000 characters).","type":"string","minLength":1,"maxLength":30000}},"required":["op","text"],"additionalProperties":false},{"description":"Rename a character (everywhere the story names them) or change their description.","type":"object","properties":{"op":{"type":"string","const":"update_character"},"characterId":{"description":"A character id from studio_script get.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"name":{"description":"The new name (up to 180 characters).","type":"string","minLength":1,"maxLength":180},"description":{"description":"The new description: how it looks and what it is (up to 2,000 characters). The next picture made for it follows the new words; pictures already made stay as they are.","type":"string","minLength":1,"maxLength":2000}},"required":["op","characterId"],"additionalProperties":false},{"description":"Rename a place (everywhere the story names it) or change its description.","type":"object","properties":{"op":{"type":"string","const":"update_location"},"locationId":{"description":"A place id from studio_script get.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"name":{"description":"The new name (up to 180 characters).","type":"string","minLength":1,"maxLength":180},"description":{"description":"The new description: how it looks and what it is (up to 2,000 characters). The next picture made for it follows the new words; pictures already made stay as they are.","type":"string","minLength":1,"maxLength":2000}},"required":["op","locationId"],"additionalProperties":false}]}}},"required":["expectedRevision","operations"],"additionalProperties":false},"example":{"expectedRevision":"sr_4f1c9a2b7d3e8a60","operations":[{"op":"set_line","scene":2,"line":2,"speaker":"character_mia"}]}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects list or create).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"revision":{"description":"The script revision now. Send it as expectedRevision with your next change.","type":"string"},"changes":{"description":"What changed, in plain words.","type":"array","items":{"type":"string"}},"undoAvailable":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"script":{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"hook":{"anyOf":[{"type":"string"},{"type":"null"}]},"storyMode":{"description":"Who speaks: mixed (the writer decides per scene: narrator, characters or both), narrated (only a narrator), dialogue (only characters), wordless (nobody).","type":"string","enum":["mixed","narrated","dialogue","wordless"]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"words":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"wordsPerSecond":{"type":"number"},"pacing":{"type":"string"},"planStale":{"description":"True after the text was edited (set_text) and before it was re-read (reanalyze): the scenes do not follow the text yet.","type":"boolean"},"narrator":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"character":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","character"],"additionalProperties":false},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"words":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pacing":{"description":"comfortable, too-fast (more words than the seconds can hold) or not-applicable.","type":"string"},"location":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},{"type":"null"}]},"action":{"description":"What the camera sees.","type":"string"},"lines":{"description":"Every spoken line, in the order it is said.","type":"array","items":{"type":"object","properties":{"line":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"speaker":{"description":"\"narrator\", or the id of the character who says it.","type":"string"},"speakerName":{"type":"string"},"text":{"type":"string"}},"required":["line","speaker","speakerName","text"],"additionalProperties":false}},"onScreenText":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["number","durationSeconds","words","pacing","location","action","lines","onScreenText"],"additionalProperties":false}},"characters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"scenes":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"pictureUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","description","scenes","pictureUrl"],"additionalProperties":{}}},"locations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"scenes":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"pictureUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","description","scenes","pictureUrl"],"additionalProperties":{}}},"objects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"scenes":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"pictureUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","description","scenes","pictureUrl"],"additionalProperties":{}}},"text":{"description":"The whole script text (with includeText).","type":"string"}},"required":["title","logline","hook","storyMode","durationSeconds","words","wordsPerSecond","pacing","planStale","narrator","scenes","characters","locations","objects"],"additionalProperties":false}},"required":["projectId","revision","changes","undoAvailable","script"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e","revision":"sr_9b2e7c41d05f3a18","changes":["Scene 1, line 1: the narrator now says \"Nobody had climbed these stairs since the storm.\"","Scene 2: Tom now also says \"Welcome home, Mia.\""],"undoAvailable":1,"script":{"title":"The Last Lighthouse","logline":"A keeper finds the lamp lit by someone who should not be there.","hook":"Nobody had climbed those stairs in forty years.","storyMode":"mixed","durationSeconds":20,"words":41,"wordsPerSecond":2.05,"pacing":"comfortable","planStale":false,"narrator":{"name":"Narrator","character":null},"scenes":[{"number":1,"durationSeconds":5,"words":8,"pacing":"comfortable","location":{"id":"location_lighthouse","name":"Lighthouse stairs"},"action":"Mia climbs the dark spiral stairs with a lantern.","lines":[{"line":1,"speaker":"narrator","speakerName":"Narrator","text":"Nobody had climbed those stairs in forty years."}],"onScreenText":"The Last Lighthouse"},{"number":2,"durationSeconds":5,"words":6,"pacing":"comfortable","location":{"id":"location_lighthouse","name":"Lighthouse stairs"},"action":"At the top the great lamp turns by itself.","lines":[{"line":1,"speaker":"character_mia","speakerName":"Mia","text":"Who lit you?"},{"line":2,"speaker":"character_tom","speakerName":"Tom","text":"I did."}],"onScreenText":null}],"characters":[{"id":"character_mia","name":"Mia","description":"A young keeper in a yellow raincoat.","scenes":[1,2],"pictureUrl":null,"role":"Hero","speaking":true,"sheetUrl":null},{"id":"character_tom","name":"Tom","description":"An old keeper with a white beard.","scenes":[2],"pictureUrl":null,"role":"Mystery","speaking":true,"sheetUrl":null}],"locations":[{"id":"location_lighthouse","name":"Lighthouse stairs","description":"A stone spiral staircase lit by one lantern.","scenes":[1,2],"pictureUrl":null}],"objects":[]}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/script/generate":{"post":{"operationId":"studio_script_generate","summary":"Write the project's script from its idea. Charged at the writer's actual use, up to the price approved; answers with a job.","description":"Writes the whole script from the project's idea, exactly as the app's Create button does: the idea as typed (or the improved brief made in the app, when it still matches the settings), the attached pictures and text files, and the project's writer, length, web search and text switches (change those first with studio_projects update). Every new film lets the writer decide, scene by scene, whether a narrator or the characters speak. The writer is billed at what it actually used, once it finishes. The price asked is the most it can cost (every word it may read, think and write for this length, at the dearest rate), and you are never charged more than the price you approved; a typical script costs far less, and a failed one costs nothing. It needs at least 200 credits in your balance to start. It runs in the background (usually a few minutes; a long film can take much longer): the answer is a job to follow with autoclips_jobs get, whose result has the new revision and what was actually charged. Read the script then with get. A project that already has a script needs replace: true; the old script is not kept (a new script cannot be undone), and pictures made for its cast are not carried over. Refused once clips are planned or a film exists, while an app tab is editing the project, and while anything else runs on it.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"studio.script.generate","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"studio_script action=generate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"replace":{"description":"Must be true when the project already has a script: the new one replaces it (it cannot be undone).","type":"boolean"},"whoSpeaks":{"description":"Who says the words in this script: auto (the writer decides), characters (no narrator), narrator (no character lines) or none. A fixed choice is guaranteed. Send it with replace: true to write the script again under another choice (the app's Change who speaks).","type":"string","enum":["auto","characters","narrator","none"]},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects list or create).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"started":{"type":"boolean"},"job":{"description":"Follow it with autoclips_jobs get. Its result has the new revision and what was actually charged.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"mode":{"type":"string","enum":["write","reanalyze"]},"writtenFrom":{"description":"idea: your idea as typed; brief: the improved brief made in the app for these settings; files / pictures: only attached files or pictures; script: the edited script text.","type":"string","enum":["idea","brief","files","pictures","script"]},"approvedCredits":{"description":"The most it can cost, as approved. Nothing is charged until it finishes.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"notes":{"type":"array","items":{"type":"string"}}},"required":["projectId","started","job","mode","writtenFrom","approvedCredits","notes"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e","started":true,"job":{"id":"job_0192a3b4c5d6e7f8a9b0c1d2","product":"studio","kind":"studio.script","resource":{"type":"project","id":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},"status":"running","step":"Writing the script","progress":null,"result":null,"error":null,"createdAt":"2026-09-29T10:00:00.000Z","updatedAt":"2026-09-29T10:00:00.000Z","finishedAt":null,"poll_after_seconds":20},"mode":"write","writtenFrom":"idea","approvedCredits":480,"notes":["The script is being written in the background (usually a few minutes; a long film can take much longer). Follow the job with autoclips_jobs get; its result says what was actually charged."]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/script/reanalyze":{"post":{"operationId":"studio_script_reanalyze","summary":"Re-read the edited script text so its scenes, cast and places follow it. Charged at actual use; answers with a job.","description":"After the whole script text was changed (edit set_text, or in the app's script box), the scenes no longer follow it. This re-reads the exact text, word for word, and plans its scenes, cast and places again, exactly as the app's \"Re-analyze changes\" button does (same writer, no pictures, no files, no web search). Billed at what the writer actually used once it finishes; the price asked is the most it can cost. Pictures made for the old cast are not carried over, and it cannot be undone. Runs in the background: follow the job with autoclips_jobs get. Refused once clips are planned or a film exists, while an app tab is editing the project, and while anything else runs on it.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"studio.script.reanalyze","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"studio_script action=reanalyze","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects list or create).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"started":{"type":"boolean"},"job":{"description":"Follow it with autoclips_jobs get. Its result has the new revision and what was actually charged.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"mode":{"type":"string","enum":["write","reanalyze"]},"writtenFrom":{"description":"idea: your idea as typed; brief: the improved brief made in the app for these settings; files / pictures: only attached files or pictures; script: the edited script text.","type":"string","enum":["idea","brief","files","pictures","script"]},"approvedCredits":{"description":"The most it can cost, as approved. Nothing is charged until it finishes.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"notes":{"type":"array","items":{"type":"string"}}},"required":["projectId","started","job","mode","writtenFrom","approvedCredits","notes"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/script/undo":{"post":{"operationId":"studio_script_undo","summary":"Take back the last script edit made here. Up to 5 steps back, while nothing else changed the script since.","description":"Puts the script back as it was before the last edit (lines, action, places, title, text, names and descriptions), as a new revision. Each undo goes one edit further back, up to 5 (fewer for very long scripts); an undo cannot itself be undone, and a new script (generate, reanalyze) cannot be undone. Only while the script is exactly as that edit left it: once the app or Studio changed it since, undo is refused. Pictures made since stay. Send expectedRevision (the revision you read). Same rules as edit otherwise.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.script.undo","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_script action=undo","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedRevision":{"description":"The script revision you read (studio_script get, revision). A stale batch is refused instead of changing the wrong lines.","type":"string","pattern":"^sr_[0-9a-f]{16}$"}},"required":["expectedRevision"],"additionalProperties":false},"example":{"expectedRevision":"sr_9b2e7c41d05f3a18"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects list or create).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"revision":{"description":"The script revision now. Send it as expectedRevision with your next change.","type":"string"},"changes":{"description":"What changed, in plain words.","type":"array","items":{"type":"string"}},"undoAvailable":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"script":{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"logline":{"anyOf":[{"type":"string"},{"type":"null"}]},"hook":{"anyOf":[{"type":"string"},{"type":"null"}]},"storyMode":{"description":"Who speaks: mixed (the writer decides per scene: narrator, characters or both), narrated (only a narrator), dialogue (only characters), wordless (nobody).","type":"string","enum":["mixed","narrated","dialogue","wordless"]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"words":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"wordsPerSecond":{"type":"number"},"pacing":{"type":"string"},"planStale":{"description":"True after the text was edited (set_text) and before it was re-read (reanalyze): the scenes do not follow the text yet.","type":"boolean"},"narrator":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"character":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","character"],"additionalProperties":false},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"words":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pacing":{"description":"comfortable, too-fast (more words than the seconds can hold) or not-applicable.","type":"string"},"location":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},{"type":"null"}]},"action":{"description":"What the camera sees.","type":"string"},"lines":{"description":"Every spoken line, in the order it is said.","type":"array","items":{"type":"object","properties":{"line":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"speaker":{"description":"\"narrator\", or the id of the character who says it.","type":"string"},"speakerName":{"type":"string"},"text":{"type":"string"}},"required":["line","speaker","speakerName","text"],"additionalProperties":false}},"onScreenText":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["number","durationSeconds","words","pacing","location","action","lines","onScreenText"],"additionalProperties":false}},"characters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"scenes":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"pictureUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","description","scenes","pictureUrl"],"additionalProperties":{}}},"locations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"scenes":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"pictureUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","description","scenes","pictureUrl"],"additionalProperties":{}}},"objects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"scenes":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"pictureUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","description","scenes","pictureUrl"],"additionalProperties":{}}},"text":{"description":"The whole script text (with includeText).","type":"string"}},"required":["title","logline","hook","storyMode","durationSeconds","words","wordsPerSecond","pacing","planStale","narrator","scenes","characters","locations","objects"],"additionalProperties":false}},"required":["projectId","revision","changes","undoAvailable","script"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e","revision":"sr_4f1c9a2b7d3e8a60","changes":["Took back: Scene 2: Tom now also says \"Welcome home, Mia.\"","0 earlier edits left to undo."],"undoAvailable":0,"script":{"title":"The Last Lighthouse","logline":"A keeper finds the lamp lit by someone who should not be there.","hook":"Nobody had climbed those stairs in forty years.","storyMode":"mixed","durationSeconds":20,"words":41,"wordsPerSecond":2.05,"pacing":"comfortable","planStale":false,"narrator":{"name":"Narrator","character":null},"scenes":[{"number":1,"durationSeconds":5,"words":8,"pacing":"comfortable","location":{"id":"location_lighthouse","name":"Lighthouse stairs"},"action":"Mia climbs the dark spiral stairs with a lantern.","lines":[{"line":1,"speaker":"narrator","speakerName":"Narrator","text":"Nobody had climbed those stairs in forty years."}],"onScreenText":"The Last Lighthouse"},{"number":2,"durationSeconds":5,"words":6,"pacing":"comfortable","location":{"id":"location_lighthouse","name":"Lighthouse stairs"},"action":"At the top the great lamp turns by itself.","lines":[{"line":1,"speaker":"character_mia","speakerName":"Mia","text":"Who lit you?"},{"line":2,"speaker":"character_tom","speakerName":"Tom","text":"I did."}],"onScreenText":null}],"characters":[{"id":"character_mia","name":"Mia","description":"A young keeper in a yellow raincoat.","scenes":[1,2],"pictureUrl":null,"role":"Hero","speaking":true,"sheetUrl":null},{"id":"character_tom","name":"Tom","description":"An old keeper with a white beard.","scenes":[2],"pictureUrl":null,"role":"Mystery","speaking":true,"sheetUrl":null}],"locations":[{"id":"location_lighthouse","name":"Lighthouse stairs","description":"A stone spiral staircase lit by one lantern.","scenes":[1,2],"pictureUrl":null}],"objects":[]}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/sheets":{"post":{"operationId":"studio_sheets_generate","summary":"Draw character sheets (every side, eight expressions) from their directions. Each lands as soon as it is done. Costs credits.","description":"Draws a character sheet for each character from its sheet direction (write them first with prepare_sheets) and its current picture. Two are drawn at a time, in the order sent; each lands on the project as soon as it is done (the job says how many are ready). Each sheet is a new version and becomes the one the clips use. characters: which ones, by id; leave it out for every character with a picture and no sheet yet (redo: true draws every one again). change: with exactly one character, what to change, in your own words. imageModel: the picture maker (default: the project's sheet picture maker, else its picture maker, else dream5). If it cannot draw a sheet, the next picture maker in line draws it and its price applies, so the quote is the price of the dearest one; you are never charged more than the price you approved, and a sheet that fails is refunded. If the project already has planned clips, new sheets clear them (they were planned with the old look): send clearPlannedClips: true to go ahead; an AI app asks first. Runs in the background: the answer is a job (autoclips_jobs get). Refused while anything else runs on the project, and, when it clears planned clips, while the project is open and saving in the app.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"studio.sheets.generate","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"studio_looks action=make_sheets","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"characters":{"description":"The characters, by id. Default: every character with a picture and no sheet yet.","minItems":1,"maxItems":10,"type":"array","items":{"description":"The id of a character, object or place (from studio_looks overview).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_.:-]+$"}},"redo":{"description":"Without characters: true draws a new sheet for every character with a picture. Default false.","type":"boolean"},"change":{"description":"Only with exactly one item: what to change in its current picture, in your own words (up to 3,000 characters), for example \"make the coat red\". The current picture is sent as a reference.","type":"string","minLength":3,"maxLength":3000},"imageModel":{"description":"Picture maker: Which model draws the characters, places, objects and character sheets.\nChoices:\n- dream5 — Dream 5: Recommended for polished 3D character and asset references. (41 credits per picture)\n- gptImage2High — ChatGPT Image 2.0 High: Strong prompt accuracy and crisp production detail. (30 credits per picture)\n- nanoBanana2 — Nano Banana 2: Fast high-quality generations with flexible references. (72 credits per picture)\nDefault: the project's sheet picture maker, else its picture maker, else dream5 (leave it out).","type":"string","enum":["dream5","gptImage2High","nanoBanana2"]},"clearPlannedClips":{"description":"Required when the project already has planned clips: a new picture, sheet or voice clears them (they were planned with the old look and must be planned again, which costs credits). Finished videos stay.","type":"boolean","const":true},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"started":{"type":"boolean","const":true},"job":{"description":"Follow it with autoclips_jobs get (or GET /v1/jobs/{id}); its result says what was made and what was charged.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"drawing":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"}},"required":["id","name","kind"],"additionalProperties":false}},"imageModel":{"type":"string"},"clipsToClear":{"type":"number"}},"required":["projectId","started","job","drawing","imageModel","clipsToClear"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/sheets/directions":{"post":{"operationId":"studio_sheets_prepare","summary":"The planning AI writes a character-sheet direction from each character's picture. Needed before make_sheets. Costs credits.","description":"A character sheet shows one character from every side with eight expressions; the clips are made from the sheets. The planning AI looks at each character's picture and writes the direction its sheet is drawn from (two characters per request, as the app does). characters: which ones, by id; leave it out for every character whose sheet direction is missing or out of date (its picture changed). Characters without a picture are skipped (named ones are refused): make their pictures first. planningModel: which AI writes them (default: the planning AI saved for the project's character sheets, else its saved planning AI, else Kimi K3). Billed at the AI's actual cost after each request; the quote is the most it can cost, and you are never charged more than the price you approved. A request that fails costs nothing. Studio needs 500 credits in your balance to start these requests. Runs in the background: the answer is a job (autoclips_jobs get). Refused while the project is open and saving in the app, and while anything else runs on it.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"studio.sheets.prepare","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"studio_looks action=prepare_sheets","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"characters":{"description":"The characters, by id. Default: every character with a picture whose sheet direction is missing or out of date.","minItems":1,"maxItems":10,"type":"array","items":{"description":"The id of a character, object or place (from studio_looks overview).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_.:-]+$"}},"planningModel":{"description":"Planning AI: Which AI plans the pictures, character sheets and clips from the script (it looks at the pictures, so only vision-capable writers). A new project starts on the app's pick for your plan.\nChoices:\n- opus55 — Claude Opus 5.5: Strongest physical logic and continuity for demanding stories. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 783 credits, a longer film or a bigger cast more (billed at the real AI cost).\n- trendScout — Kimi K3: Strong, timely, research-led story development. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 589 credits, a longer film or a bigger cast more (billed at the real AI cost).\n- quickSpark — Gemini 3.8 Flash: Fast brainstorming with clear visual beats. Planning a typical 30-second film (its pictures, character sheets and clips) costs about 150 credits, a longer film or a bigger cast more (billed at the real AI cost).\nDefault: the planning AI saved for the project's character sheets, else its saved planning AI, else Kimi K3 (leave it out).","type":"string","enum":["opus55","trendScout","quickSpark"]},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio project id (from studio_projects).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio project id (from studio_projects).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"started":{"type":"boolean","const":true},"job":{"description":"Follow it with autoclips_jobs get (or GET /v1/jobs/{id}); its result says what was made and what was charged.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"preparing":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"}},"required":["id","name","kind"],"additionalProperties":false}},"skipped":{"description":"Characters whose sheet direction is already up to date.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"}},"required":["id","name","kind"],"additionalProperties":false}},"withoutPicture":{"description":"Characters left out because they have no picture yet.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"}},"required":["id","name","kind"],"additionalProperties":false}},"planningModel":{"type":"string"},"requests":{"type":"number"}},"required":["projectId","started","job","preparing","skipped","withoutPicture","planningModel","requests"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/soundtrack":{"post":{"operationId":"studio_soundtrack_generate","summary":"Compose a new soundtrack take for the film, optionally in a chosen direction. Charged per take; answers with a job.","description":"Writes a music brief from the film's scenes and clip timings, and Studio's AI soundtrack composes one continuous instrumental. Each call is a NEW take and is charged: about 36 credits, settled to the provider's actual cost, so the quote is up to 54; you are never charged more than the price you approved. direction: a proposal id from soundtrack_ideas, or your own words (up to 600 characters). If the take fails, the credits are given back. The new take is laid under the video the next time the clips are joined. Refused while the film uses a track of its own (your upload or a popular track): switch the source to studio with soundtrack_settings first. Runs in the background (a minute or two); refused while anything else runs on the film.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"studio.soundtrack.generate","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"studio_finish action=make_soundtrack","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"direction":{"description":"A proposal id from soundtrack_ideas (like \"direction-2\"), or the music you want in your own words. Default: the film's current direction.","type":"string","minLength":3,"maxLength":600},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"started":{"description":"True when background work started; follow it with autoclips_jobs get.","type":"boolean"},"job":{"description":"The background work, when some started.","anyOf":[{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},{"type":"null"}]},"direction":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"styleTags":{"type":"array","items":{"type":"string"}},"custom":{"type":"boolean"}},"required":["id","name","summary","styleTags","custom"],"additionalProperties":false},{"type":"null"}]},"usualCredits":{"description":"What a take usually costs; the actual charge is in the job's result.","type":"number"}},"required":["projectId","started","job","direction","usualCredits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"studio_soundtrack_update","summary":"Set where the film's music comes from (Studio's, your own or a popular track), how loud it is, or mute it.","description":"Changes the soundtrack settings saved on the film: source (studio: Studio's composed take; native: the video model scores the clip itself, only for a single clip of 30 seconds or less with native audio on; upload: your own track, added with studio_finish use_own_track or in the AutoClips app; popular: a well-known song from Studio's short list, picked with popularMusicId), volume (0-100; a new film starts at 30) and muted. Every setting you leave out keeps what the film has now. Popular tracks today: pixy-legacy-slowed-reverb (\"LEGACY (slowed + reverb)\" by PIXY). Popular songs are not licensed by AutoClips: YouTube, TikTok or Instagram may mute or claim a video that uses one. They apply the next time the clips are joined; the finished videos you have stay as they are. Free. Refused while the film is open in the AutoClips app or anything else runs on it.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.soundtrack.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_finish action=soundtrack_settings","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"description":"Soundtrack: Where the music comes from.\nChoices:\n- studio — Studio soundtrack: An AI soundtrack written for the story. (36 credits per soundtrack take)\n- native — Scored inside the clip: The video model scores the clip itself. Only for a single clip of 30 seconds or less with native audio on.\n- upload — Your own track: A track you upload (MP3, WAV, M4A, AAC, OGG, FLAC or AIFF, 2 seconds to 10 minutes). (Free)\n- popular — A popular track: A well-known song picked from a short list (popularMusicId). Popular songs are not licensed by AutoClips: YouTube, TikTok or Instagram may mute or claim a video that uses one. (Free)\nDefault: the film's current source, or popular when you send popularMusicId (leave it out).","type":"string","enum":["studio","native","upload","popular"]},"popularMusicId":{"description":"Popular track: A well-known song laid under the whole film instead of Studio's score (soundtrack source popular). Popular songs are not licensed by AutoClips: YouTube, TikTok or Instagram may mute or claim a video that uses one. It loops when it is shorter than the video. Free: nothing is composed or charged.\nChoices:\n- pixy-legacy-slowed-reverb — LEGACY (slowed + reverb): PIXY, 2:43. Not licensed by AutoClips: a platform can mute or claim the video. (Free)\nDefault: The track the film already has picked (leave it out).","type":"string","enum":["pixy-legacy-slowed-reverb"]},"volume":{"description":"Music volume: How loud the soundtrack is under the voices, in percent. From 0 to 100 percent. Default: the film's current volume, which starts at 30 on a new film (leave it out).","type":"integer","minimum":0,"maximum":100},"muted":{"description":"true: no music at all under the video. Default: the film's current setting, which is not muted on a new film (leave it out).","type":"boolean"}},"additionalProperties":false},"example":{"volume":15}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"soundtrack":{"type":"object","properties":{"source":{"description":"Where the music comes from now, as the next join lays it: studio (Studio's composed take), native (scored inside the clip), upload (your own track) or popular (the popular track picked). A picked track that is no longer there falls back to studio.","type":"string","enum":["studio","native","upload","popular"]},"volume":{"type":"number"},"muted":{"type":"boolean"},"music":{"anyOf":[{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["name","status","url","durationSeconds"],"additionalProperties":false},{"type":"null"}]},"customTrack":{"anyOf":[{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","url"],"additionalProperties":false},{"type":"null"}]},"popularTrack":{"anyOf":[{"description":"The popular track picked on this film (a well-known song AutoClips does not license: a platform can mute or claim a video that uses it).","type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"artist":{"type":"string"},"durationSeconds":{"type":"number"},"url":{"description":"Listen to it here.","type":"string"}},"required":["id","title","artist","durationSeconds","url"],"additionalProperties":false},{"type":"null"}]},"direction":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"styleTags":{"type":"array","items":{"type":"string"}},"custom":{"type":"boolean"}},"required":["id","name","summary","styleTags","custom"],"additionalProperties":false},{"type":"null"}]}},"required":["source","volume","muted","music","customTrack","popularTrack","direction"],"additionalProperties":false},"changed":{"type":"boolean"},"message":{"type":"string"}},"required":["projectId","soundtrack","changed","message"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/soundtrack/directions":{"post":{"operationId":"studio_soundtrack_directions","summary":"Three different soundtrack directions written for this film, to pick one for make_soundtrack.","description":"An AI music supervisor pitches three clearly different scores for the film (the proposals are kept on the film, so asking again returns the same ones for free unless refresh is true). Pick one by its id in make_soundtrack, or describe your own. Free; counts toward the daily limit for free AI helpers.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.soundtrack.directions","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_finish action=soundtrack_ideas","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"refresh":{"description":"true: write new proposals even if the film already has some. Default false.","type":"boolean"}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"styleTags":{"type":"array","items":{"type":"string"}},"custom":{"type":"boolean"}},"required":["id","name","summary","styleTags","custom"],"additionalProperties":false}},"reused":{"description":"True when these are the proposals the film already had.","type":"boolean"},"chosen":{"description":"The direction the film uses now, if one was picked.","anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"styleTags":{"type":"array","items":{"type":"string"}},"custom":{"type":"boolean"}},"required":["id","name","summary","styleTags","custom"],"additionalProperties":false},{"type":"null"}]}},"required":["projectId","options","reused","chosen"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/soundtrack/own-track":{"post":{"operationId":"studio_soundtrack_set_custom","summary":"Use a sound from your media library as the film's soundtrack: levelled and stored like an upload in the app. Free.","description":"Makes your own track the film's soundtrack, exactly as uploading it in the app's final video step does: the sound (from your media library, MP3, WAV, M4A, AAC, OGG, FLAC or AIFF, 2 seconds to 10 minutes, up to 50 MB) is checked, brought to Studio's soundtrack loudness with one plain gain, re-encoded to a stereo MP3 with its tags and cover art removed, and stored in your Studio folder. The film's music source becomes upload; Studio's own take stays on the film, so switching back with soundtrack_settings (source studio) is free. Free. Each call prepares and stores a new copy, and counts toward the daily limit for uploads and imports. Takes a few seconds (up to about a minute for a long track). The track is laid under the video the next time the clips are joined; the finished videos stay as they are. Needs the film's script. Refused while an app tab is editing the project (it saved in the last 90 seconds) and while Studio is working on the film (a step, the clips, a soundtrack take, a finishing step, an edited cut rendering, or Autopilot). An app tab that had the film open before this change keeps the new track when it saves. One gap: in a tab opened after this change, going back to the old soundtrack (removing this track, or picking Studio's music) as the very first change there does not stick; make any other change in that tab first, or switch here with soundtrack_settings (source studio). Bring a sound into your library first with autoclips_media (upload_link or import_url).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.soundtrack.set_custom","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_finish action=use_own_track","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mediaId":{"description":"A sound in your media library (autoclips_media list, upload_link or import_url): MP3, WAV, M4A, AAC, OGG, FLAC or AIFF, 2 seconds to 10 minutes, up to 50 MB.","type":"string","pattern":"^[a-fA-F0-9]{24}$"},"name":{"description":"The name the track shows under in the app. Default: the file's name in your media library.","type":"string","minLength":1,"maxLength":120,"pattern":"^[^\\u0000-\\u001f\\u007f\\u202A-\\u202E\\u2066-\\u2069]+$"}},"required":["mediaId"],"additionalProperties":false},"example":{"mediaId":"66f7c0ffee00000000000003"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"soundtrack":{"type":"object","properties":{"source":{"description":"Where the film's music comes from now: upload = your own track, popular = the popular track picked, studio = Studio's composed take, native = scored inside the clip.","type":"string","enum":["studio","native","upload","popular"]},"volume":{"description":"Music level under the video, 0-100.","type":"number"},"muted":{"type":"boolean"},"ownTrack":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"length":{"description":"The track's length, like 2:34.","type":"string"},"loudnessLufs":{"description":"How loud the original was (LUFS), before it was levelled.","anyOf":[{"type":"number"},{"type":"null"}]},"gainDb":{"description":"The one plain gain that brought it to Studio's soundtrack level (dB).","type":"number"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","url","durationSeconds","length","loudnessLufs","gainDb","createdAt"],"additionalProperties":false},{"type":"null"}]},"popularTrack":{"anyOf":[{"description":"The popular track picked on this film (a well-known song AutoClips does not license: a platform can mute or claim a video that uses it).","type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"artist":{"type":"string"},"durationSeconds":{"type":"number"},"url":{"description":"Listen to it here.","type":"string"}},"required":["id","title","artist","durationSeconds","url"],"additionalProperties":false},{"type":"null"}]}},"required":["source","volume","muted","ownTrack","popularTrack"],"additionalProperties":false},"message":{"type":"string"}},"required":["projectId","soundtrack","message"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e","soundtrack":{"source":"upload","volume":30,"muted":false,"ownTrack":{"id":"5d0c2a9e-7f1b-4c3d-9e8f-1a2b3c4d5e6f","name":"summer-theme.mp3","url":"https://media.autoclips.app/generated-images/studio-v2/user-id/music-uploads/5d0c2a9e-7f1b-4c3d-9e8f-1a2b3c4d5e6f.mp3","durationSeconds":154.2,"length":"2:34","loudnessLufs":-19.6,"gainDb":5.6,"createdAt":"2026-09-29T10:00:00.000Z"},"popularTrack":null},"message":"Your track is now the film's soundtrack. It is laid under the video the next time the clips are joined; the finished videos you have stay as they are. Change its level or go back to Studio's music with soundtrack_settings (source studio)."}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/stitch":{"post":{"operationId":"studio_video_stitch","summary":"Join the chosen clip videos into the film, with its soundtrack, text on top and outro, at its speed. Free; a job.","description":"Joins the clip videos each clip card has chosen (select_version chooses another) into one film: frozen frames trimmed, joins smoothed, the film's soundtrack (if it has one; this never composes one) and Studio's text on top drawn, and the outro added when one is switched on, all with the film's saved settings. speed sets how fast it plays (free; saved on the film, as the app's Speed row and its free \"Apply\" re-join do); left out, the film's saved speed is used, which is 1.1x for a new film and 1x for a film first joined before speeds existed. The new film becomes the film's video; earlier ones are kept, and its titles and captions are written for it. Free; counts toward the daily limit for free AI helpers. Needs every clip made, from a whole version. It runs in the background (a minute or two): follow the job. Refused while the film is open in the app or anything else runs on it.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.video.stitch","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_clips action=stitch","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"speed":{"description":"Final video speed: How fast the finished video plays. Every clip plays faster with its voices at their own pitch; the soundtrack and the outro stay at normal speed. A finished video lasts its clips' seconds divided by the speed. Free: clips are priced by the seconds rendered, which the speed does not change. A film joined before speeds existed stays at 1x until a speed is chosen.\nChoices:\n- 1 — 1x: Normal speed, as the clips were rendered. (Free)\n- 1.1 — 1.1x: A little quicker than rendered. What a new film plays at. (Free)\n- 1.25 — 1.25x: Recommended: the quick pace short-form edits use. (Free)\n- 1.5 — 1.5x: 1.5 times as fast as rendered. (Free)\n- 2 — 2x: 2 times as fast as rendered. (Free)\nDefault: The film's saved speed; a new film plays at 1.1x (leave it out).\nSend the value as text (\"1.25\") or a number (1.25).","anyOf":[{"description":"Final video speed: How fast the finished video plays. Every clip plays faster with its voices at their own pitch; the soundtrack and the outro stay at normal speed. A finished video lasts its clips' seconds divided by the speed. Free: clips are priced by the seconds rendered, which the speed does not change. A film joined before speeds existed stays at 1x until a speed is chosen.\nChoices:\n- 1 — 1x: Normal speed, as the clips were rendered. (Free)\n- 1.1 — 1.1x: A little quicker than rendered. What a new film plays at. (Free)\n- 1.25 — 1.25x: Recommended: the quick pace short-form edits use. (Free)\n- 1.5 — 1.5x: 1.5 times as fast as rendered. (Free)\n- 2 — 2x: 2 times as fast as rendered. (Free)\nDefault: The film's saved speed; a new film plays at 1.1x (leave it out).","type":"string","enum":["1","2","1.1","1.25","1.5"]},{"type":"number","enum":[1,1.1,1.25,1.5,2]}]}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"9b2f7c1e-4d3a-4f6b-8e21-6c0d5a7e3f19"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"soundtrack":{"description":"What music the film will carry, in plain words.","type":"string"},"speed":{"description":"How fast the film will play (1 is normal speed).","type":"number"}},"required":["projectId","job","soundtrack","speed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/text-on-top":{"get":{"operationId":"studio_finish_text_get","summary":"Every word Studio drew on top of a finished video: key, words, timing, look.","description":"Lists the titles, chat messages, labels and end card Studio drew over a finished video, each with the key edit_text needs, its words, when it shows (and when it was planned to), its look, and whether it is hidden. Also the changes already made and the limits.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"studio.finish.text_get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_finish action=get_text","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"videoId","in":"query","required":false,"schema":{"description":"Which finished video. Default: the film's current video.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"Which finished video. Default: the film's current video."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"videoId":{"type":"string"},"textVideoId":{"description":"The version whose words are edited (under a watermark or outro, the version beneath).","anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string","enum":["editable","off","failed","fixed","none","no-video"]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]},"entries":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"kind":{"type":"string"},"text":{"type":"string"},"words":{"description":"The text's words as wordColors counts them: index 0 is the first.","type":"array","items":{"type":"string"}},"originalText":{"type":"string"},"scene":{"anyOf":[{"type":"number"},{"type":"null"}]},"startMs":{"type":"number"},"endMs":{"type":"number"},"plannedStartMs":{"type":"number"},"plannedEndMs":{"type":"number"},"shown":{"type":"boolean"},"added":{"type":"boolean"},"style":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"sender":{"type":"string"},"side":{"type":"string","enum":["incoming","outgoing"]}},"required":["key","kind","text","words","originalText","scene","startMs","endMs","plannedStartMs","plannedEndMs","shown","added","style"],"additionalProperties":false}},"edits":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"text":{"type":"string"},"style":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"timing":{"type":"object","properties":{"startShiftMs":{"type":"number"},"durationMs":{"type":"number"}},"additionalProperties":false},"hidden":{"type":"boolean"},"added":{"type":"boolean"},"startMs":{"type":"number"},"endMs":{"type":"number"}},"required":["key"],"additionalProperties":false}},"limits":{"type":"object","properties":{"maxEdits":{"type":"number"},"maxAdded":{"type":"number"},"characters":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"fonts":{"type":"array","items":{"type":"string"}}},"required":["maxEdits","maxAdded","characters","fonts"],"additionalProperties":false}},"required":["projectId","videoId","textVideoId","state","message","entries","edits","limits"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"studio_finish_text_edits","summary":"Change, move, restyle, hide or add the words drawn on top of a finished video. Answers with a job.","description":"Redraws Studio's words on a finished video with your changes and makes the result the film's video (nothing is joined again; free). Get the keys with get_text. By default your changes are laid on the changes already made (field by field); replaceAll: true makes this list the whole set (use it to apply ask_text's proposal). Up to 60 changes and 20 added texts. A watermark or outro on the chosen video sits on top of the old words, so the new version has none: add them again afterwards. Runs in the background (about half a minute). Refused while the film is open in the AutoClips app or anything else runs on it.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.finish.text_edits","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_finish action=edit_text","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"videoId":{"description":"One finished video of this film: its id from studio_projects get (include videos).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"edits":{"description":"The changes, up to 60. One change to the words on top. key names the text: a key from get_text for Studio's own texts (\"kind|scene|original words\"), or \"title|added|<4-24 lowercase letters or digits>\" / \"label|added|...\" for a text you add. Studio's texts take text (new words: messages up to 90 characters, labels 40, titles 60, end cards 80), style (place, font, colour, size, and wordColors: [{ index, color }] to colour single words, index counting the words from 0), timing ({ startShiftMs, durationMs } moves it from its planned moment) and hidden (true removes it from the video). An added text needs added: true, text, startMs and endMs (on the video's clock). reset: true drops every change to that text (an added text is removed).","maxItems":60,"type":"array","items":{"description":"One change to the words on top. key names the text: a key from get_text for Studio's own texts (\"kind|scene|original words\"), or \"title|added|<4-24 lowercase letters or digits>\" / \"label|added|...\" for a text you add. Studio's texts take text (new words: messages up to 90 characters, labels 40, titles 60, end cards 80), style (place, font, colour, size, and wordColors: [{ index, color }] to colour single words, index counting the words from 0), timing ({ startShiftMs, durationMs } moves it from its planned moment) and hidden (true removes it from the video). An added text needs added: true, text, startMs and endMs (on the video's clock). reset: true drops every change to that text (an added text is removed).","type":"object","properties":{"key":{"description":"Which text: see get_text.","type":"string","minLength":3,"maxLength":280},"text":{"type":"string","minLength":1,"maxLength":90,"pattern":"[\\p{L}\\p{N}]"},"style":{"type":"object","properties":{"x":{"description":"Where the middle of the text sits across the frame, in percent: 0 left edge, 100 right edge.","type":"number","minimum":0,"maximum":100},"y":{"description":"Where it sits down the frame, in percent: 0 top, 100 bottom. For a chat thread: where its newest bubble ends.","type":"number","minimum":0,"maximum":100},"font":{"description":"The typeface: anton, montserrat, bebas, oswald, poppins, roboto, lato, urbanist, bangers, marker, blackops, delius.","type":"string","enum":["anton","montserrat","bebas","oswald","poppins","roboto","lato","urbanist","bangers","marker","blackops","delius"]},"color":{"description":"Letter colour, #RRGGBB.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"background":{"description":"Bubble or pill colour for a message or label, #RRGGBB (titles have none).","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"size":{"description":"Size in percent of the kind's normal size (50 to 200).","type":"integer","minimum":50,"maximum":200},"icon":{"description":"false: a label pill without its link icon.","type":"boolean","const":false},"wordColors":{"description":"Single words in their own colour (every other word keeps color), up to 60. Replaces the text's earlier word colours; [] clears them. When you change the words and leave this out, each coloured word keeps its colour if it is still there.","maxItems":60,"type":"array","items":{"type":"object","properties":{"index":{"description":"Which word: its place among the text's words (get_text lists them as words), counted from 0.","type":"integer","minimum":0,"maximum":99},"color":{"description":"That word's colour, #RRGGBB.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}},"required":["index","color"],"additionalProperties":false}}},"additionalProperties":false},"timing":{"type":"object","properties":{"startShiftMs":{"description":"Move its start by this many milliseconds (negative = earlier).","type":"integer","minimum":-600000,"maximum":600000},"durationMs":{"description":"How long it stays on screen, in milliseconds (at least 500).","type":"integer","minimum":500,"maximum":600000}},"additionalProperties":false},"hidden":{"type":"boolean"},"reset":{"type":"boolean","const":true},"added":{"type":"boolean","const":true},"startMs":{"description":"Added texts: when it appears, in milliseconds from the start of the video.","type":"integer","minimum":0,"maximum":600000},"endMs":{"description":"Added texts: when it goes away, in milliseconds.","type":"integer","minimum":0,"maximum":1200000}},"required":["key"],"additionalProperties":false}},"replaceAll":{"description":"true: these edits are the whole set; every text not named goes back to how Studio planned it. Default false: they are laid on the changes already made.","type":"boolean"}},"required":["videoId","edits"],"additionalProperties":false},"example":{"videoId":"final-video-7c1e","edits":[{"key":"title|1|the last lighthouse","style":{"y":12,"color":"#FFD166"}}]}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"started":{"description":"True when background work started; follow it with autoclips_jobs get.","type":"boolean"},"job":{"description":"The background work, when some started.","anyOf":[{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},{"type":"null"}]},"videoId":{"type":"string"},"textVideoId":{"type":"string"},"edits":{"description":"The whole set of changes the new version is drawn with.","type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"text":{"type":"string"},"style":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"timing":{"type":"object","properties":{"startShiftMs":{"type":"number"},"durationMs":{"type":"number"}},"additionalProperties":false},"hidden":{"type":"boolean"},"added":{"type":"boolean"},"startMs":{"type":"number"},"endMs":{"type":"number"}},"required":["key"],"additionalProperties":false}},"removesFinishing":{"description":"True when the chosen video had a watermark or outro, which the new version will not have.","type":"boolean"},"message":{"type":"string"}},"required":["projectId","started","job","videoId","textVideoId","edits","removesFinishing","message"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/text-on-top/ask":{"post":{"operationId":"studio_finish_text_agent","summary":"Say in plain words how the text on top should change; an AI proposes the edits (nothing is changed).","description":"An AI reads your instruction (\"move the title to the top and make it yellow\", \"keep the website up for five seconds\") and answers with the full list of edits, built on the changes already on the video. Nothing is saved or drawn: show the proposal to the user, then apply it with edit_text (videoId, those edits, replaceAll: true). Free; counts toward the daily limit for free AI helpers. Instruction up to 600 characters.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.finish.text_agent","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_finish action=ask_text","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"videoId":{"description":"One finished video of this film: its id from studio_projects get (include videos).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"instruction":{"description":"What should change, in plain words.","type":"string","minLength":2,"maxLength":600}},"required":["videoId","instruction"],"additionalProperties":false},"example":{"videoId":"final-video-7c1e","instruction":"Move the title to the top and make it yellow."}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"videoId":{"type":"string"},"summary":{"type":"string"},"edits":{"description":"The proposed whole set of edits. Apply with edit_text and replaceAll: true.","type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"text":{"type":"string"},"style":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"timing":{"type":"object","properties":{"startShiftMs":{"type":"number"},"durationMs":{"type":"number"}},"additionalProperties":false},"hidden":{"type":"boolean"},"added":{"type":"boolean"},"startMs":{"type":"number"},"endMs":{"type":"number"}},"required":["key"],"additionalProperties":false}},"changedKeys":{"type":"array","items":{"type":"string"}}},"required":["projectId","videoId","summary","edits","changedKeys"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/timeline":{"post":{"operationId":"studio_timeline_open","summary":"Studio 2.0: open a finished video on the timeline (as the app's Edit video does) and get its variantId for get, edit and render.","description":"Studio 2.0 only. Each finished video of a Studio film has its own editor cut. This finds or makes the cut for one video (the film's current video unless you name videoId), exactly as the app's Edit video button does, and answers its variantId. Then use the timeline actions on it: get with { product: \"studio\", projectId, variantId } (REST GET /timeline/studio/{projectId}?variantId=...), then edit, undo, render. Send the same variantId every time, so every call works on this cut. Free, and safe to call again: a cut the editor already has work on is opened as it is; one nobody has edited yet is brought up to date with its video first. While Studio is working on the film (a step, the clips, a soundtrack take, a finishing step, an edited cut rendering, or Autopilot), a cut that still has to be made or refreshed waits: try again when it finishes.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.timeline.open","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_timeline action=open_studio_cut","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"videoId":{"description":"One finished video of this film: its id from studio_projects get (include videos).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id: a V3 project id, or a Studio 2.0 project id.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The project id: a V3 project id, or a Studio 2.0 project id.","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"variantId":{"type":"string"},"created":{"description":"True when this video had no editor cut until now.","type":"boolean"},"hasEdits":{"description":"True when the editor already has changes saved on this cut.","type":"boolean"},"video":{"type":"object","properties":{"id":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"madeIn":{"type":"string","enum":["studio","editor"]},"selected":{"description":"Whether this is the film's current video.","type":"boolean"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","url","durationSeconds","madeIn","selected","createdAt"],"additionalProperties":false},"timeline":{"description":"Exactly what to send to the timeline actions (get, edit, undo, redo, render).","type":"object","properties":{"product":{"type":"string","const":"studio"},"projectId":{"type":"string"},"variantId":{"type":"string"}},"required":["product","projectId","variantId"],"additionalProperties":false},"links":{"type":"object","properties":{"editor":{"type":"string"}},"required":["editor"],"additionalProperties":{}},"next":{"type":"string"}},"required":["projectId","variantId","created","hasEdits","video","timeline","links","next"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e","variantId":"final-video-7c1e","created":false,"hasEdits":false,"video":{"id":"final-video-7c1e","url":"https://media.autoclips.app/kling-videos/studio-v2/user-id/final/final-video-7c1e.mp4","durationSeconds":30,"madeIn":"studio","selected":true,"createdAt":"2026-09-28T09:00:00.000Z"},"timeline":{"product":"studio","projectId":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e","variantId":"final-video-7c1e"},"links":{"editor":"https://app.autoclips.app/editor/b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e?variant=final-video-7c1e"},"next":"Read it with autoclips_timeline get (product \"studio\", projectId \"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e\", variantId \"final-video-7c1e\"), then edit, undo or render it with the same three."}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/projects/{projectId}/watermark":{"post":{"operationId":"studio_finish_watermark","summary":"Burn a text or logo watermark into a finished video, or take it off. Answers with a job.","description":"Draws your watermark (a line of text, or a logo picture from your media library) on every frame of a finished video of the film and makes that the film's video. Free. Every setting you leave out keeps the film's saved watermark setting; a template sets the look (font, style, size, place) and keeps your text or logo. The mark always goes onto a clean video, so marks never stack. It runs in the background (usually under a minute): follow the job. type \"none\" takes the watermark off by switching back to the version without it (no render). Refused while the film is open in the AutoClips app or anything else runs on it.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.finish.watermark","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_finish action=watermark","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceVideoId":{"description":"Which finished video gets the mark. Default: the film's current video. A video that already has a watermark is swapped for its clean original first.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"type":{"description":"Watermark: A mark burned into the finished video.\nChoices:\n- none — None: No watermark.\n- text — Text: Your handle or brand name as text.\n- image — Logo picture: Your logo, uploaded as a picture.\nDefault: the kind the template, imageMediaId or text you send makes, else the film's saved watermark type (leave it out).","type":"string","enum":["none","text","image"]},"text":{"description":"The watermark words, one line, up to 60 characters (for example your handle).","type":"string","minLength":1,"maxLength":60,"pattern":"^[^\\r\\n\\t]*$"},"imageMediaId":{"description":"A logo picture from your media library (upload it with autoclips_media first; a PNG with a see-through background looks best, up to 10 MB). Makes this a logo watermark.","type":"string","pattern":"^[a-f0-9]{24}$"},"template":{"description":"Watermark look: A ready-made look; it keeps your text or logo and sets font, style, size and place.\nChoices:\n- handle — Handle: Handle look for a text watermark.\n- stamp — Stamp: Stamp look for a text watermark.\n- ticker — Ticker: Ticker look for a text watermark.\n- signature — Signature: Signature look for a text watermark.\n- whisper — Whisper: Whisper look for a text watermark.\n- playful — Playful: Playful look for a text watermark.\n- corner-logo — Corner logo: Corner logo look for a logo watermark.\n- faint-centre — Faint centre: Faint centre look for a logo watermark.\n- top-badge — Top badge: Top badge look for a logo watermark.\nDefault: None (set each field yourself) (leave it out).","type":"string","enum":["handle","stamp","ticker","signature","whisper","playful","corner-logo","faint-centre","top-badge"]},"font":{"description":"Watermark font: The font of a text watermark.\nChoices:\n- clean — Noto Sans: Noto Sans lettering.\n- bold — Bandico: Bandico lettering.\n- thin — Montserrat: Montserrat lettering.\n- friendly — Delius: Delius lettering.\n- script — Monsieur: Monsieur lettering.\n- caps — Bebas Neue: Bebas Neue lettering.\n- impact — Anton: Anton lettering.\n- oswald — Oswald: Oswald lettering.\n- poppins — Poppins: Poppins lettering.\n- roboto — Roboto: Roboto lettering.\n- urbanist — Urbanist: Urbanist lettering.\n- lato — Lato: Lato lettering.\n- bangers — Bangers: Bangers lettering.\n- blackops — Black Ops: Black Ops lettering.\n- marker — Marker: Marker lettering.\nDefault: the template's when you pick one, else the film's saved watermark font, else clean (leave it out).","type":"string","enum":["clean","bold","thin","friendly","script","caps","impact","oswald","poppins","roboto","urbanist","lato","bangers","blackops","marker"]},"textStyle":{"description":"Watermark text style: How a text watermark stands out from the video.\nChoices:\n- shadow — Shadow: Shadow text.\n- plain — Plain: Plain text.\n- outline — Outline: Outline text.\n- box — Box: Box text.\nDefault: the template's when you pick one, else the film's saved watermark text style, else shadow (leave it out).","type":"string","enum":["shadow","plain","outline","box"]},"color":{"description":"Text colour, #RRGGBB. Default: the template's when you pick one, else the film's saved watermark colour, else #FFFFFF (leave it out).","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"opacity":{"description":"Watermark opacity: How solid the watermark is, in percent. From 10 to 100 percent. Default: the template's when you pick one, else the film's saved watermark opacity, else 85 (leave it out).","type":"integer","minimum":10,"maximum":100},"size":{"description":"Watermark size: Size of the watermark, in percent of normal. From 25 to 300 percent. Default: the template's when you pick one, else the film's saved watermark size, else 100 (leave it out).","type":"integer","minimum":25,"maximum":300},"position":{"description":"Watermark position: Where the watermark sits.\nChoices:\n- top-left — Top left: Top left of the frame.\n- top-center — Top centre: Top centre of the frame.\n- top-right — Top right: Top right of the frame.\n- middle-left — Middle left: Middle left of the frame.\n- center — Centre: Centre of the frame.\n- middle-right — Middle right: Middle right of the frame.\n- bottom-left — Bottom left: Bottom left of the frame.\n- bottom-center — Bottom centre: Bottom centre of the frame.\n- bottom-right — Bottom right: Bottom right of the frame.\nDefault: the template's when you pick one, else the film's saved watermark position, else bottom-right (leave it out).","type":"string","enum":["top-left","top-center","top-right","middle-left","center","middle-right","bottom-left","bottom-center","bottom-right"]},"startSeconds":{"description":"When the mark appears, in seconds of the finished video (rounded to a tenth). Default: the film's saved watermark start, else 0 (leave it out).","type":"number","minimum":0,"maximum":600},"endSeconds":{"description":"When it goes away, in seconds; 0 means until the end. Default: the film's saved watermark end, else 0, the whole video (leave it out).","type":"number","minimum":0,"maximum":600}},"additionalProperties":false},"example":{"type":"text","text":"@mybrand","template":"handle"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The Studio film's project id (from studio_projects list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The Studio film's project id (from studio_projects list).","example":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"started":{"description":"True when background work started; follow it with autoclips_jobs get.","type":"boolean"},"job":{"description":"The background work, when some started.","anyOf":[{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},{"type":"null"}]},"video":{"description":"The version that is now the film's video, when no render was needed.","anyOf":[{"type":"object","properties":{"id":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"aspectRatio":{"anyOf":[{"type":"string"},{"type":"null"}]},"watermark":{"description":"The watermark burned into this version, if any.","anyOf":[{"type":"string","enum":["text","image"]},{"type":"null"}]},"outro":{"description":"Whether this version ends with an outro.","type":"boolean"},"builtOn":{"description":"The version this one was made from.","anyOf":[{"type":"string"},{"type":"null"}]},"speed":{"description":"How fast this video plays: 1 = as rendered, 1.25 = a quarter faster (voices keep their pitch).","type":"number"},"selected":{"description":"Whether this is the film's current video.","type":"boolean"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","url","durationSeconds","aspectRatio","watermark","outro","builtOn","speed","selected","createdAt"],"additionalProperties":false},{"type":"null"}]},"builtOn":{"description":"The clean video the mark is drawn on.","anyOf":[{"type":"object","properties":{"id":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"aspectRatio":{"anyOf":[{"type":"string"},{"type":"null"}]},"watermark":{"description":"The watermark burned into this version, if any.","anyOf":[{"type":"string","enum":["text","image"]},{"type":"null"}]},"outro":{"description":"Whether this version ends with an outro.","type":"boolean"},"builtOn":{"description":"The version this one was made from.","anyOf":[{"type":"string"},{"type":"null"}]},"speed":{"description":"How fast this video plays: 1 = as rendered, 1.25 = a quarter faster (voices keep their pitch).","type":"number"},"selected":{"description":"Whether this is the film's current video.","type":"boolean"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","url","durationSeconds","aspectRatio","watermark","outro","builtOn","speed","selected","createdAt"],"additionalProperties":false},{"type":"null"}]},"watermark":{"type":"object","properties":{"type":{"type":"string","enum":["none","text","image"]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]},"logoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"font":{"type":"string"},"textStyle":{"type":"string"},"color":{"type":"string"},"opacity":{"type":"number"},"size":{"type":"number"},"position":{"anyOf":[{"type":"string"},{"type":"null"}]},"x":{"type":"number"},"y":{"type":"number"},"startSeconds":{"type":"number"},"endSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["type","text","logoUrl","font","textStyle","color","opacity","size","position","x","y","startSeconds","endSeconds"],"additionalProperties":false},"message":{"type":"string"}},"required":["projectId","started","job","video","builtOn","watermark","message"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e","started":true,"job":{"id":"job_0192a3b4c5d6e7f8a9b0c1d2","product":"studio","kind":"studio.watermark","resource":{"type":"project","id":"b7e3c1d2-4f5a-4b6c-9d7e-8f9a0b1c2d3e"},"status":"running","step":"Drawing the watermark on every frame","progress":null,"result":null,"error":null,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","finishedAt":null,"poll_after_seconds":15},"video":null,"builtOn":{"id":"final-video-7c1e","url":"https://media.autoclips.app/kling-videos/studio-v2/u/final.mp4","durationSeconds":30,"aspectRatio":"9:16","watermark":null,"outro":false,"builtOn":null,"speed":1.1,"selected":true,"createdAt":"2026-09-28T09:00:00.000Z"},"watermark":{"type":"image","text":null,"logoUrl":"https://media.autoclips.app/generated-images/studio-v2/u/api-watermarks/logo.png","font":"clean","textStyle":"shadow","color":"#FFFFFF","opacity":50,"size":100,"position":"top-center","x":50,"y":5,"startSeconds":0,"endSeconds":null},"message":"Drawing the watermark."}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/studio/promotion/extract":{"post":{"operationId":"studio_promotion_extract","summary":"Read a product page (or pasted product text) into product details for a promotion. Nothing is saved. Free.","description":"Studio reads a public product page (url) or the product's own words you paste (text, up to 20,000 characters) and fills in the product details a promotion needs: name, kind, what it is, benefits, what sets it apart, audience and tone. Nothing is saved: check the details with the user, then save them with set_promotion (add website: the same link). Free; counts toward the daily limit for free AI helpers, and has its own daily limit of 5 reads (50 on a paid plan). Only public web pages are read.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["3D Animated Studio 2.0"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"studio.promotion.extract","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"studio_ideas action=extract_product","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"description":"A public product page.","type":"string","maxLength":2000,"pattern":"^https?:\\/\\/\\S+$"},"text":{"description":"The product's own words instead of a page: a description, a listing, a manual.","type":"string","minLength":20,"maxLength":20000},"productName":{"description":"The product's name, when you know it (helps on pages that list several).","type":"string","minLength":1,"maxLength":120}},"additionalProperties":false},"example":{"url":"https://example.com/products/oat-milk-barista","productName":"Barista Oat Milk"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"product":{"type":"object","properties":{"name":{"type":"string"},"productType":{"type":"string"},"whatItIs":{"type":"string"},"benefits":{"type":"array","items":{"type":"string"}},"differentiators":{"type":"array","items":{"type":"string"}},"audience":{"type":"string"},"tone":{"type":"string"}},"required":["name","productType","whatItIs","benefits","differentiators","audience","tone"],"additionalProperties":false},"from":{"type":"string","enum":["website","text"]},"website":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["product","from","website"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/timeline/music":{"get":{"operationId":"shared_timeline_music","summary":"Search the editor's Music tab for add_music: popular songs and the music library, with ids, lengths and moods.","description":"Searches the same tracks the editor's Music tab offers: the popular songs first (category popular, ids starting with popular-), then the AutoClips music library. Every word of search must match a track's name, artist, mood or tags. Categories: popular, general, crime, space, history, animals, horror, science. Popular songs are not licensed by AutoClips: YouTube, TikTok or Instagram may mute or claim a video that uses one. Each popular song in the answer says so; tell the user before adding one. The other tracks are the AutoClips music library, the one the videos are made with. Free.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.timeline.music","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_timeline action=music","parameters":[{"name":"search","in":"query","required":false,"schema":{"description":"Words to look for, like \"tense crime\" or \"slowed reverb\".","type":"string","maxLength":80},"description":"Words to look for, like \"tense crime\" or \"slowed reverb\".","example":"dark"},{"name":"category","in":"query","required":false,"schema":{"description":"popular for the popular songs; the others are library moods.","type":"string","enum":["popular","general","crime","space","history","animals","horror","science"]},"description":"popular for the popular songs; the others are library moods.","example":"popular"},{"name":"limit","in":"query","required":false,"schema":{"description":"How many to return (default 20).","type":"integer","minimum":1,"maximum":50},"description":"How many to return (default 20).","example":5}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"musicId":{"description":"What add_music takes.","type":"string"},"title":{"type":"string"},"artist":{"type":"string"},"category":{"type":"string"},"durationMs":{"description":"How long the track is; add_music loops it under a longer video.","type":"number"},"description":{"type":"string"},"popular":{"description":"A popular song AutoClips does not license.","type":"boolean"},"warning":{"type":"string"}},"required":["musicId","title","category","durationMs","description","popular"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"categories":{"type":"array","items":{"type":"string"}},"notes":{"description":"The rights warning, when a popular song is listed.","type":"array","items":{"type":"string"}}},"required":["items","total","categories","notes"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"items":[{"musicId":"popular-pixy-legacy-slowed-reverb","title":"LEGACY (slowed + reverb)","artist":"PIXY","category":"popular","durationMs":162800,"description":"PIXY · popular in short-form edits","popular":true,"warning":"Popular songs are not licensed by AutoClips: YouTube, TikTok or Instagram may mute or claim a video that uses one."}],"total":1,"categories":["popular","general","crime","space","history","animals","horror","science"],"notes":["Popular songs are not licensed by AutoClips: YouTube, TikTok or Instagram may mute or claim a video that uses one."]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/timeline/sounds":{"get":{"operationId":"shared_timeline_sounds","summary":"Search the sound effect library for add_sound_effect: ids, names, lengths and what each one sounds like.","description":"Searches the same sound effects the editor offers (door creaks, whooshes, impacts, ambience and more). Every word of search must match the effect's name, description or tags. Categories: horror, ambient, impact, transition, foley, musical, chat.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.timeline.sounds","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_timeline action=sounds","parameters":[{"name":"search","in":"query","required":false,"schema":{"description":"Words to look for, like \"door creak\" or \"whoosh\".","type":"string","maxLength":80},"description":"Words to look for, like \"door creak\" or \"whoosh\".","example":"door creak"},{"name":"category","in":"query","required":false,"schema":{"type":"string","enum":["horror","ambient","impact","transition","foley","musical","chat"]},"example":"transition"},{"name":"limit","in":"query","required":false,"schema":{"description":"How many to return (default 20).","type":"integer","minimum":1,"maximum":50},"description":"How many to return (default 20).","example":5}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"sfxId":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"durationMs":{"type":"number"},"description":{"type":"string"}},"required":["sfxId","title","category","durationMs","description"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"categories":{"type":"array","items":{"type":"string"}}},"required":["items","total","categories"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/timeline/{product}/{projectId}":{"get":{"operationId":"shared_timeline_get","summary":"Read a video's timeline: its revision, rows, clips with ids and times, captions, markers and render state.","description":"Opens the timeline the way the AutoClips editor does: the saved edits, or the video as it was made when nobody has edited it yet. Every clip has an id, its row, its start and end in milliseconds and as \"0:03-0:07\", what it shows or says, and for scenes their number, spoken words and transition in. Captions and a video's own sound are rows the editor builds from the scenes, so they are summarised rather than listed. A Studio 2.0 chat bubble sent by me can keep the name it had while it was sent by them: its sender is still listed, but the video shows no name on it, and its note says so. Up to 80 clips by default (limit, up to 200); ask for one row with track. The revision is what edit needs as expectedRevision.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.timeline.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_timeline action=get","parameters":[{"name":"product","in":"path","required":true,"schema":{"description":"Which product the video belongs to: v3 (a V3 cinematic story), studio (a Studio 2.0 video) or editor (a Video Editor project, made with autoclips_editor create).","type":"string","enum":["v3","studio","editor"]},"description":"Which product the video belongs to: v3 (a V3 cinematic story), studio (a Studio 2.0 video) or editor (a Video Editor project, made with autoclips_editor create).","example":"v3"},{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Video Editor project id (edit_…).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Video Editor project id (edit_…).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},{"name":"variantId","in":"query","required":false,"schema":{"description":"Studio 2.0 only: which cut (finished video) to work on. Leave it out for the first cut; get lists every cut under \"cuts\". Send back the variantId you read, so every call works on the same cut.","type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.-]*$"},"description":"Studio 2.0 only: which cut (finished video) to work on. Leave it out for the first cut; get lists every cut under \"cuts\". Send back the variantId you read, so every call works on the same cut.","example":"ver_20260927"},{"name":"track","in":"query","required":false,"schema":{"description":"Only list the clips on this row.","type":"string","enum":["video","overlay","text","sound_effects","audio","music","studio_text"]},"description":"Only list the clips on this row.","example":"sound_effects"},{"name":"limit","in":"query","required":false,"schema":{"description":"How many clips to list (default 80).","type":"integer","minimum":1,"maximum":200},"description":"How many clips to list (default 80)."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"product":{"type":"string","enum":["v3","studio","editor"]},"projectId":{"type":"string"},"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"cuts":{"description":"Studio 2.0: every cut of the project that opens in the editor.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"hasEdits":{"type":"boolean"}},"required":["id","label","hasEdits"],"additionalProperties":false}},"revision":{"description":"Send this as expectedRevision with your next edit.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasSavedEdits":{"type":"boolean"},"title":{"type":"string"},"aspect":{"type":"string"},"durationMs":{"type":"number"},"duration":{"type":"string"},"videoSpeed":{"type":"number"},"tracks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"clips":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"muted":{"type":"boolean"},"hidden":{"type":"boolean"},"locked":{"type":"boolean"}},"required":["id","label","kind","clips"],"additionalProperties":false}},"clips":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"track":{"description":"video, overlay, studio_text, text, sound_effects, audio or music.","type":"string"},"kind":{"description":"image, video, text, studio-text or audio.","type":"string"},"scene":{"description":"Scenes only: its number, counting from 1.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"startMs":{"type":"number"},"endMs":{"type":"number"},"time":{"description":"The same times as \"0:03-0:07\".","type":"string"},"label":{"type":"string"},"text":{"type":"string"},"caption":{"description":"Scenes only: the words spoken in it.","type":"string"},"captionsOff":{"type":"boolean"},"media":{"type":"object","properties":{"kind":{"type":"string"},"url":{"type":"string"}},"required":["kind","url"],"additionalProperties":false},"transitionIn":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"durationMs":{"type":"number"}},"required":["type","name","durationMs"],"additionalProperties":false},"sound":{"description":"What set_clip_sound can change, as it is now.","type":"object","properties":{"on":{"type":"boolean"},"volumeDb":{"description":"Volume in dB, 0 as recorded. On music that dips under the narrator's words, the level between the lines (underVoiceDb is the level under them).","type":"number"},"fadeInMs":{"type":"number"},"fadeOutMs":{"type":"number"},"dipUnderVoice":{"description":"Music only: it really is lowered while the narrator speaks, as the video plays it. False when its dip is off, on a video with no narrator, and on older V3 music (made before 2026-10-05) that does not follow the narrator's words: that plays at a steady volumeDb under the voice, though the editor shows its dip switched on, and its note says so.","type":"boolean"},"dipUnderClipSound":{"description":"Music only: it is also lowered under talking recorded in the videos.","type":"boolean"},"dipDb":{"description":"Music only: how far it dips (dB), when it dips.","type":"number"},"underVoiceDb":{"description":"Music that dips under the narrator only: its level under the voice (volumeDb + dipDb).","type":"number"},"note":{"description":"Older music that plays at a steady level under the narrator says so here, and how to make it dip.","type":"string"}},"required":["on","volumeDb","fadeInMs","fadeOutMs"],"additionalProperties":false},"visibleArea":{"description":"Scenes only, when reframe moved it off the middle: which part of the picture shows where it is not the frame's shape.","type":"object","properties":{"x":{"description":"0 left edge, 50 middle, 100 right edge.","type":"number"},"y":{"description":"0 top, 50 middle, 100 bottom.","type":"number"}},"required":["x","y"],"additionalProperties":false},"sfxId":{"type":"string"},"musicId":{"description":"Music only: the track it came from (an id from the music action).","type":"string"},"warning":{"description":"A popular song: AutoClips does not license it.","type":"string"},"studio":{"description":"Studio 2.0 texts only: what set_studio_text_style can change, as it is now.","type":"object","properties":{"kind":{"description":"title, message (a chat bubble), label (a pill) or end_card.","type":"string","enum":["title","end_card","message","label"]},"words":{"description":"Its words, counting from 0: what wordColors in set_studio_text_style points at.","type":"array","items":{"type":"string"}},"side":{"description":"A chat message only: incoming (sent by them, left) or outgoing (sent by me, right).","type":"string","enum":["incoming","outgoing"]},"sender":{"description":"A chat message only: its name. The video shows the name only on a bubble sent by them. A bubble sent by me keeps the name it had, but the video shows none (its note says so). \"\" is no name.","type":"string"},"note":{"description":"A chat bubble sent by me that kept a name: says the video does not show that name.","type":"string"},"look":{"type":"object","properties":{"font":{"type":"string"},"color":{"type":"string"},"background":{"type":"string"},"size":{"description":"Percent of the kind's usual size.","type":"number"},"x":{"description":"Percent across the frame; null is its usual place.","anyOf":[{"type":"number"},{"type":"null"}]},"y":{"description":"Percent down the frame; null is its usual place.","anyOf":[{"type":"number"},{"type":"null"}]},"icon":{"type":"boolean"},"wordColors":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"color":{"type":"string"}},"required":["index","color"],"additionalProperties":false}},"custom":{"description":"True when anything differs from the kind's default look.","type":"boolean"}},"required":["font","color","size","x","y","wordColors","custom"],"additionalProperties":false}},"required":["kind","words","look"],"additionalProperties":false},"hidden":{"type":"boolean"},"locked":{"type":"boolean"}},"required":["id","track","kind","startMs","endMs","time","label"],"additionalProperties":false}},"clipsShown":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clipsTotal":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"trimmed":{"anyOf":[{"type":"string"},{"type":"null"}]},"captions":{"type":"object","properties":{"enabled":{"type":"boolean"},"style":{"type":"string"},"font":{"type":"string"},"position":{"type":"string"},"size":{"type":"number"},"color":{"type":"string"},"highlightColor":{"type":"string"},"background":{"type":"boolean"},"wordsOnScreen":{"type":"number"},"scenesWithWords":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"scenesOff":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["enabled","style","font","position","size","color","highlightColor","background","wordsOnScreen","scenesWithWords","scenesOff"],"additionalProperties":false},"markers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"atMs":{"type":"number"},"at":{"type":"string"},"label":{"type":"string"}},"required":["id","atMs","at","label"],"additionalProperties":false}},"render":{"anyOf":[{"type":"object","properties":{"status":{"description":"idle, queued, rendering, finishing, completed, failed or cancelled.","type":"string"},"progress":{"type":"number"},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"description":"The finished video, once completed.","anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"canCancel":{"type":"boolean"},"stale":{"description":"True when the render stopped reporting for a while; asking again re-checks it with the render service.","type":"boolean"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastVideo":{"description":"The last video the editor finished, and which revision it was made from.","anyOf":[{"type":"object","properties":{"videoUrl":{"type":"string"},"revision":{"anyOf":[{"type":"number"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["videoUrl","revision","finishedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["status","progress","stage","videoUrl","error","canCancel","stale","startedAt","lastVideo"],"additionalProperties":false},{"type":"null"}]},"links":{"type":"object","properties":{"editor":{"type":"string"}},"required":["editor"],"additionalProperties":false}},"required":["product","projectId","variantId","revision","hasSavedEdits","title","aspect","durationMs","duration","videoSpeed","tracks","clips","clipsShown","clipsTotal","trimmed","captions","markers","render","links"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"product":"v3","projectId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","variantId":null,"revision":4,"hasSavedEdits":true,"title":"The lighthouse keeper","aspect":"9:16","durationMs":9000,"duration":"0:09","videoSpeed":1,"tracks":[{"id":"video","label":"Video","kind":"video","clips":2},{"id":"overlay","label":"Overlay","kind":"video","clips":0},{"id":"text","label":"Text","kind":"text","clips":0},{"id":"sound_effects","label":"Sound effects","kind":"audio","clips":1},{"id":"audio","label":"Audio","kind":"audio","clips":0},{"id":"music","label":"Music","kind":"audio","clips":1}],"clips":[{"id":"clp_k3x9a2_s_1","track":"video","kind":"image","scene":1,"startMs":0,"endMs":4000,"time":"0:00-0:04","label":"Every night he climbed","caption":"Every night he climbed the stairs","media":{"kind":"image","url":"https://media.autoclips.app/generated-images/lamp.png"}},{"id":"clp_k3x9a2_s_2","track":"video","kind":"image","scene":2,"startMs":4000,"endMs":9000,"time":"0:04-0:09","label":"Until the door creaked","caption":"Until the door creaked open","transitionIn":{"type":"mix","name":"Mix","durationMs":600},"media":{"kind":"image","url":"https://media.autoclips.app/generated-images/door.png"}},{"id":"clp_k3x9a2_fx_1","track":"sound_effects","kind":"audio","startMs":5200,"endMs":8200,"time":"0:05.2-0:08.2","label":"Creak Door Slow","sfxId":"creak-door-slow","media":{"kind":"audio","url":"https://media.autoclips.app/sound-effects/v3/horror/creak-door-slow.mp3"},"sound":{"on":true,"volumeDb":0,"fadeInMs":0,"fadeOutMs":0}},{"id":"clp_k3x9a2_mu_1","track":"music","kind":"audio","startMs":0,"endMs":9000,"time":"0:00-0:09","label":"Night Tide","sound":{"on":true,"volumeDb":-14,"fadeInMs":1500,"fadeOutMs":3000,"dipUnderVoice":true,"dipUnderClipSound":false,"dipDb":-6,"underVoiceDb":-20}}],"clipsShown":4,"clipsTotal":4,"trimmed":null,"captions":{"enabled":true,"style":"glow","font":"BebasNeue","position":"lower-third","size":68,"color":"#FFFFFF","highlightColor":"#FF2222","background":false,"wordsOnScreen":3,"scenesWithWords":2,"scenesOff":0},"markers":[],"render":{"status":"completed","progress":100,"stage":null,"videoUrl":"https://media.autoclips.app/videos/v3_cinematic_lighthouse.mp4","error":null,"canCancel":false,"stale":false,"startedAt":null,"lastVideo":null},"links":{"editor":"https://app.autoclips.app/editor/b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"shared_timeline_edit","summary":"Change a timeline: up to 25 edits (cut, trim, move, add media, text, sounds, music, transitions, captions, style), saved together.","description":"Applies up to 25 operations in order, each seeing what the ones before it did, with the editor's own commands, and saves them as one new revision. All or nothing: if any operation is refused, nothing is saved and the answer says which one and why. expectedRevision must be the revision you read; if the timeline changed since, the answer is revision_conflict and nothing is saved. Media must be in your own media library; the media rules are checked again when it is saved. An edit that would make the video play longer than the product allows (a slower speed counts) is refused. The answer lists every change in plain words and returns the new timeline. Free. add_music lays a track from the music action under the whole video, at the editor's level for that video. On a video with a narrator the editor lays music at -14 dB between the narrator's lines, dipping 6 dB under the words (to -20 dB); on one without, at a steady -20 dB. Popular songs are not licensed by AutoClips: YouTube, TikTok or Instagram may mute or claim a video that uses one. change_music swaps the song under the music already there (one clip, or all of it) and keeps its volume, fades and dip, like the editor's \"Change track\"; delete the music clip to remove the music. set_clip_sound changes volume, mute and fades, and how music dips under speech, like the editor's sound panel; get shows each sound's settings under sound. reframe picks which part of a scene's picture shows when it is not the frame's shape, like dragging the video in the editor's preview; get shows it under visibleArea. set_studio_text_style changes the look of Studio 2.0's own texts (font, colours, single word colours, size, place), like the editor's inspector; get lists each one's words, counted from 0, under studio.words.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.timeline.edit","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_timeline action=edit","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"variantId":{"description":"Studio 2.0 only: which cut (finished video) to work on. Leave it out for the first cut; get lists every cut under \"cuts\". Send back the variantId you read, so every call works on the same cut.","type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.-]*$"},"expectedRevision":{"description":"The revision you read with get (or got back from your last edit). If the timeline changed since, nothing is saved and the answer is revision_conflict: read it again and redo the edit.","type":"integer","minimum":0,"maximum":1000000000},"operations":{"description":"The edits, in order. Each has an \"op\" and its own fields.","minItems":1,"maxItems":25,"type":"array","items":{"anyOf":[{"description":"Cut a clip in two at a time inside it.","type":"object","properties":{"op":{"type":"string","const":"split"},"clipId":{"description":"A clip id from get.","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"},"at":{"description":"A time: a number is milliseconds from the start of the video; text is read the way a person says it. Times can be \"3:36\", \"216s\", \"1m 5s\", \"2s into scene 3\", \"the start of scene 2\", \"the end of scene 4\", \"the middle of scene 2\" or \"when she says 'money'\". Ranges can be \"3:36 to 3:52\", \"3:36-3:52\", \"2s into scene 3 for 4 seconds\", \"scene 2\" or \"the last 5 seconds\".","anyOf":[{"type":"integer","minimum":0,"maximum":21600000},{"type":"string","minLength":1,"maxLength":200}]}},"required":["op","clipId","at"],"additionalProperties":false},{"description":"Delete clips. Deleting a scene closes the gap and takes what sits on it along.","type":"object","properties":{"op":{"type":"string","const":"delete"},"clipIds":{"minItems":1,"maxItems":20,"type":"array","items":{"description":"A clip id from get.","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"}}},"required":["op","clipIds"],"additionalProperties":false},{"description":"Copy clips and put the copies right after them.","type":"object","properties":{"op":{"type":"string","const":"duplicate"},"clipIds":{"minItems":1,"maxItems":20,"type":"array","items":{"description":"A clip id from get.","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"}}},"required":["op","clipIds"],"additionalProperties":false},{"description":"Move a clip that is not a scene to a new start time, or onto another row. Scenes are reordered with reorder.","type":"object","properties":{"op":{"type":"string","const":"move"},"clipId":{"description":"A clip id from get.","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"},"to":{"description":"Where it should start.","anyOf":[{"type":"integer","minimum":0,"maximum":21600000},{"type":"string","minLength":1,"maxLength":200}]},"track":{"description":"Move it onto another row as well. A picture moved onto the video row becomes a scene at the nearest place between scenes.","type":"string","enum":["video","overlay","text","sound_effects","audio","music"]}},"required":["op","clipId","to"],"additionalProperties":false},{"description":"Make a clip shorter or longer from its start or its end. A scene lasts 1 to 30 seconds (up to 10 minutes in a Video Editor project); the scenes after it move to match.","type":"object","properties":{"op":{"type":"string","const":"trim"},"clipId":{"description":"A clip id from get.","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"},"edge":{"description":"Which end of the clip to move.","type":"string","enum":["start","end"]},"at":{"description":"Where that end should be. To make the last scene longer than the video is now, give milliseconds.","anyOf":[{"type":"integer","minimum":0,"maximum":21600000},{"type":"string","minLength":1,"maxLength":200}]}},"required":["op","clipId","edge","at"],"additionalProperties":false},{"description":"Change the order of scenes on the video row.","type":"object","properties":{"op":{"type":"string","const":"reorder"},"clipId":{"description":"A clip id from get.","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"},"toIndex":{"description":"The scene's new place, counting from 1 (1 = first).","type":"integer","minimum":1,"maximum":1000}},"required":["op","clipId","toIndex"],"additionalProperties":false},{"description":"Add a picture or video from your library as a new scene or as an overlay.","type":"object","properties":{"op":{"type":"string","const":"add_media"},"mediaId":{"description":"A picture, video or sound from your media library (its id from autoclips_media).","type":"string","pattern":"^[a-f0-9]{24}$"},"at":{"description":"A time: a number is milliseconds from the start of the video; text is read the way a person says it. Times can be \"3:36\", \"216s\", \"1m 5s\", \"2s into scene 3\", \"the start of scene 2\", \"the end of scene 4\", \"the middle of scene 2\" or \"when she says 'money'\". Ranges can be \"3:36 to 3:52\", \"3:36-3:52\", \"2s into scene 3 for 4 seconds\", \"scene 2\" or \"the last 5 seconds\".","anyOf":[{"type":"integer","minimum":0,"maximum":21600000},{"type":"string","minLength":1,"maxLength":200}]},"track":{"description":"video (default): a new scene at the nearest place between scenes. overlay: on top of the video, small in the top-right corner.","type":"string","enum":["video","overlay"]},"durationMs":{"description":"How long it shows. A scene lasts 1 to 30 seconds (up to 10 minutes in a Video Editor project). Default 4 seconds for a picture, 5 for a video; in a Video Editor project a video plays its whole length.","type":"integer","minimum":250,"maximum":600000}},"required":["op","mediaId","at"],"additionalProperties":false},{"description":"Show a different picture or video in a clip, keeping its length and place.","type":"object","properties":{"op":{"type":"string","const":"replace_media"},"clipId":{"description":"A clip id from get.","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"},"mediaId":{"description":"A picture, video or sound from your media library (its id from autoclips_media).","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["op","clipId","mediaId"],"additionalProperties":false},{"description":"Put text on the video.","type":"object","properties":{"op":{"type":"string","const":"add_text"},"text":{"type":"string","minLength":1,"maxLength":300},"at":{"description":"A time: a number is milliseconds from the start of the video; text is read the way a person says it. Times can be \"3:36\", \"216s\", \"1m 5s\", \"2s into scene 3\", \"the start of scene 2\", \"the end of scene 4\", \"the middle of scene 2\" or \"when she says 'money'\". Ranges can be \"3:36 to 3:52\", \"3:36-3:52\", \"2s into scene 3 for 4 seconds\", \"scene 2\" or \"the last 5 seconds\".","anyOf":[{"type":"integer","minimum":0,"maximum":21600000},{"type":"string","minLength":1,"maxLength":200}]},"durationMs":{"description":"How long it shows (default 4 seconds, or to the end of the video).","type":"integer","minimum":250,"maximum":600000},"position":{"description":"top (a big title), middle or bottom (default, a subtitle line).","type":"string","enum":["top","middle","bottom"]}},"required":["op","text","at"],"additionalProperties":false},{"description":"Change a text: its words, colour or size, or who sent a Studio 2.0 chat message.","type":"object","properties":{"op":{"type":"string","const":"update_text"},"clipId":{"description":"A clip id from get.","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"},"text":{"description":"The new words. On a Studio 2.0 text, coloured words keep their colours when the same words are still there.","type":"string","minLength":1,"maxLength":300},"color":{"description":"Text colour, like #FFFFFF (your own texts only; a Studio 2.0 text uses set_studio_text_style).","type":"string","pattern":"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"},"fontSize":{"description":"Text size in pixels (your own texts only; a Studio 2.0 text uses set_studio_text_style).","type":"integer","minimum":12,"maximum":240},"sender":{"description":"A Studio 2.0 chat message only: the name shown on a bubble sent by them. \"\" shows no name. A bubble sent by me shows none, so a name is refused there.","type":"string","maxLength":40},"side":{"description":"A Studio 2.0 chat message only: incoming (sent by them, left) or outgoing (sent by me, right).","type":"string","enum":["incoming","outgoing"]}},"required":["op","clipId"],"additionalProperties":false},{"description":"Change the look of one of Studio 2.0's texts, as the editor's inspector does: font, colours, single word colours, size, link icon and place. A chat's font, size and place are shared by all its bubbles.","type":"object","properties":{"op":{"type":"string","const":"set_studio_text_style"},"clipId":{"description":"One of Studio 2.0's texts (a clip on the studio_text row).","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"},"reset":{"description":"Put its default look back first (the inspector's Default look); other fields are then applied on top.","type":"boolean","const":true},"font":{"description":"The typeface: anton, montserrat, bebas, oswald, poppins, roboto, lato, urbanist, bangers, marker, blackops, delius. null puts the kind's own font back.","anyOf":[{"type":"string","enum":["anton","montserrat","bebas","oswald","poppins","roboto","lato","urbanist","bangers","marker","blackops","delius"]},{"type":"null"}]},"color":{"description":"Letter colour, like #FFFFFF. null puts the default back.","anyOf":[{"type":"string","pattern":"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"},{"type":"null"}]},"background":{"description":"Bubble colour of a chat message or pill colour of a label (titles and end cards have none). null puts the default back.","anyOf":[{"type":"string","pattern":"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"},{"type":"null"}]},"size":{"description":"Size in percent of the kind's usual size (50 to 200; 100 is usual). null puts it back.","anyOf":[{"type":"integer","minimum":50,"maximum":200},{"type":"null"}]},"icon":{"description":"A label only: false hides its link icon, true (or null) shows it.","anyOf":[{"type":"boolean"},{"type":"null"}]},"x":{"description":"Where the middle of the text sits across the frame, in percent: 0 left edge, 100 right edge. Not for a chat message, which moves up or down only. null puts it back in its usual place.","anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"y":{"description":"Where it sits down the frame, in percent: 0 top, 100 bottom. For a chat: where its newest bubble ends. null puts it back in its usual place.","anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"wordColors":{"description":"Single words in their own colour (up to 60). The list replaces the text's earlier word colours: send every coloured word you want to keep. [] or null clears them; the other words keep the text colour.","anyOf":[{"maxItems":60,"type":"array","items":{"type":"object","properties":{"index":{"description":"The word's place among the text's words, counting from 0 (get lists them under studio.words).","type":"integer","minimum":0,"maximum":99},"color":{"description":"Its colour, like #FFD166.","type":"string","pattern":"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"}},"required":["index","color"],"additionalProperties":false}},{"type":"null"}]}},"required":["op","clipId"],"additionalProperties":false},{"description":"Add a sound effect from the AutoClips library at a time.","type":"object","properties":{"op":{"type":"string","const":"add_sound_effect"},"sfxId":{"description":"A sound effect id from the sounds action.","type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"at":{"description":"A time: a number is milliseconds from the start of the video; text is read the way a person says it. Times can be \"3:36\", \"216s\", \"1m 5s\", \"2s into scene 3\", \"the start of scene 2\", \"the end of scene 4\", \"the middle of scene 2\" or \"when she says 'money'\". Ranges can be \"3:36 to 3:52\", \"3:36-3:52\", \"2s into scene 3 for 4 seconds\", \"scene 2\" or \"the last 5 seconds\".","anyOf":[{"type":"integer","minimum":0,"maximum":21600000},{"type":"string","minLength":1,"maxLength":200}]}},"required":["op","sfxId","at"],"additionalProperties":false},{"description":"Add a sound from your library (a voice-over, a song) on the audio row.","type":"object","properties":{"op":{"type":"string","const":"add_audio"},"mediaId":{"description":"A picture, video or sound from your media library (its id from autoclips_media).","type":"string","pattern":"^[a-f0-9]{24}$"},"at":{"description":"A time: a number is milliseconds from the start of the video; text is read the way a person says it. Times can be \"3:36\", \"216s\", \"1m 5s\", \"2s into scene 3\", \"the start of scene 2\", \"the end of scene 4\", \"the middle of scene 2\" or \"when she says 'money'\". Ranges can be \"3:36 to 3:52\", \"3:36-3:52\", \"2s into scene 3 for 4 seconds\", \"scene 2\" or \"the last 5 seconds\".","anyOf":[{"type":"integer","minimum":0,"maximum":21600000},{"type":"string","minLength":1,"maxLength":200}]},"gainDb":{"description":"Volume in dB: 0 as recorded, -6 quieter, +6 louder.","type":"number","minimum":-40,"maximum":6},"durationMs":{"description":"How long it plays (default 10 seconds, or to the end of the video).","type":"integer","minimum":250,"maximum":600000}},"required":["op","mediaId","at"],"additionalProperties":false},{"description":"Lay a music track under the whole video, as the editor's Music tab does: from the start to the end, looping and fading in and out, at the editor's level for this video (over a narrator it is louder between the lines and dips under the words). Tracks already on the Music row keep playing. Free. Popular songs are not licensed by AutoClips: YouTube, TikTok or Instagram may mute or claim a video that uses one.","type":"object","properties":{"op":{"type":"string","const":"add_music"},"musicId":{"description":"A track from the music action (the editor's Music tab). Ids starting with popular- are popular songs. Popular songs are not licensed by AutoClips: YouTube, TikTok or Instagram may mute or claim a video that uses one.","type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"gainDb":{"description":"Volume in dB, 0 as recorded. Default: the editor's level for this video. On a video with a narrator the editor lays music at -14 dB between the narrator's lines, dipping 6 dB under the words (to -20 dB); on one without, at a steady -20 dB. On a narrated video gainDb is the level between the lines and the dip stays the same.","type":"number","minimum":-40,"maximum":6}},"required":["op","musicId"],"additionalProperties":false},{"description":"Change the music to another song, as the editor's \"Change track\" and Music tab do: the new song keeps the old one's place, volume, fades and dip under the voice, and plays from its start. Without clipId, all the music on the Music row is replaced by this one song. Refused when the Music row is empty (use add_music). Free.","type":"object","properties":{"op":{"type":"string","const":"change_music"},"musicId":{"description":"A track from the music action (the editor's Music tab). Popular songs are not licensed by AutoClips: YouTube, TikTok or Instagram may mute or claim a video that uses one. Send musicId or mediaId, not both.","type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"mediaId":{"description":"A song from your own media library (autoclips_media), instead of musicId.","type":"string","pattern":"^[a-f0-9]{24}$"},"clipId":{"description":"The music clip to swap (a clip on the music row; get lists them). Leave it out to change all the music: the first track takes the new song under the whole video and the others go.","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"}},"required":["op"],"additionalProperties":false},{"description":"Change the sound of a video scene, a sound effect, a sound or the music, as the editor's sound panel does: volume, mute, fade in and out, and for music how it dips under speech.","type":"object","properties":{"op":{"type":"string","const":"set_clip_sound"},"clipId":{"description":"A clip id from get.","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"},"volumeDb":{"description":"Volume in dB: 0 as recorded, -6 quieter, +6 louder. On music that dips under the narrator's words (get shows underVoiceDb), this is the level between the lines.","type":"number","minimum":-40,"maximum":6},"muted":{"description":"true to silence it, false to hear it.","type":"boolean"},"fadeInMs":{"description":"How long it fades in, in milliseconds: 0 to 8000 on music, 0 to 3000 on anything else, as in the editor. 0 is no fade.","type":"integer","minimum":0,"maximum":8000},"fadeOutMs":{"description":"How long it fades out, in milliseconds: 0 to 8000 on music, 0 to 3000 on anything else, as in the editor. 0 is no fade.","type":"integer","minimum":0,"maximum":8000},"dipUnderVoice":{"description":"Music only: lower the music while the narrator speaks (the editor's \"Under the voiceover\"). Older V3 music that does not follow the narrator's words (get shows dipUnderVoice false and a note) plays at a steady level under the voice, though the editor shows its dip switched on. true makes it follow them, as the editor does when that switch is turned off and on: its volume becomes the level between the lines, so under the voice it stays where it was and between the lines it is louder by its dip. Send volumeDb and dipDb with it to pick both levels. The answer says the new levels.","type":"boolean"},"dipUnderClipSound":{"description":"Music only, with its dip switched on (the editor's \"Under the voiceover\"; dipUnderVoice: true, sent now or before): also lower it under talking recorded in the videos, like Studio 2.0 clips (the editor's \"Under the clips' own sound\").","type":"boolean"},"dipDb":{"description":"Music only, with its dip switched on (the editor's \"Under the voiceover\"; dipUnderVoice: true, sent now or before): how far it dips, -30 to 0 dB (the editor's \"Dip by\"; -6 on music laid over a narrator). The first dip change on older music that does not follow the narrator's words yet makes it follow them, as in the editor: its volume becomes the level between the lines, so what plays under the voice moves only by the change in the dip. The answer says the new levels.","type":"integer","minimum":-30,"maximum":0}},"required":["op","clipId"],"additionalProperties":false},{"description":"Pick which part of a scene's picture shows when it is not the frame's shape (a tall video in a 16:9 frame shows only a band across its middle), like dragging the video in the editor's preview or its Visible area sliders. Only the direction the picture overhangs the frame changes anything. get shows it under visibleArea.","type":"object","properties":{"op":{"type":"string","const":"reframe"},"clipId":{"description":"A scene on the Video row (a video or a picture).","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"},"x":{"description":"Across: 0 shows the left edge of the picture, 50 the middle, 100 the right edge.","type":"number","minimum":0,"maximum":100},"y":{"description":"Down: 0 shows the top of the picture, 50 the middle, 100 the bottom.","type":"number","minimum":0,"maximum":100}},"required":["op","clipId"],"additionalProperties":false},{"description":"Set how one scene starts after the one before it.","type":"object","properties":{"op":{"type":"string","const":"set_transition"},"toClipId":{"description":"The scene the transition leads INTO (never the first scene).","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"},"type":{"description":"A transition from the editor's catalog. hard-cut means no transition.","type":"string","enum":["hard-cut","mix","black-fade","overlap-fade","swipe-left","luma-wipe","zoom-switch","white-flash","whip-pan","whip-up","whip-down","zoom-punch","swipe-left-blur","velocity-stretch","cross-zoom","snap-back","spin-whirl","record-scratch","film-burn","luma-fade","glow-dissolve","iris-reveal","flare-switch","superimpose","shadow-sweep","frame-swipe","chroma-wave","signal-lost","film-mash","negative-breaks","slime-glitch","glitch-pop","off-color-burst","red-overgrowth","shake-flare","slight-jitter","vibration-amped","dust-flurry","soccer-pool","love-shockwave","flash-rotate","flip-3d","cube-spin","helix-showcase","dimensional-vortex","magical-twirl","cartoon-swirl","warp-dissolve","fan-out","peel-off","spin-clockwise","glass-cutting","pink-avalanche"]},"durationMs":{"description":"How long it takes (default: the transition's own length).","type":"integer","minimum":100,"maximum":1500}},"required":["op","toClipId","type"],"additionalProperties":false},{"description":"Make one scene start with a straight cut.","type":"object","properties":{"op":{"type":"string","const":"remove_transition"},"toClipId":{"description":"The scene whose transition in should go.","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"}},"required":["op","toClipId"],"additionalProperties":false},{"description":"Use the same transition between every pair of scenes.","type":"object","properties":{"op":{"type":"string","const":"set_transition_everywhere"},"type":{"description":"A transition from the editor's catalog. hard-cut clears them all.","type":"string","enum":["hard-cut","mix","black-fade","overlap-fade","swipe-left","luma-wipe","zoom-switch","white-flash","whip-pan","whip-up","whip-down","zoom-punch","swipe-left-blur","velocity-stretch","cross-zoom","snap-back","spin-whirl","record-scratch","film-burn","luma-fade","glow-dissolve","iris-reveal","flare-switch","superimpose","shadow-sweep","frame-swipe","chroma-wave","signal-lost","film-mash","negative-breaks","slime-glitch","glitch-pop","off-color-burst","red-overgrowth","shake-flare","slight-jitter","vibration-amped","dust-flurry","soccer-pool","love-shockwave","flash-rotate","flip-3d","cube-spin","helix-showcase","dimensional-vortex","magical-twirl","cartoon-swirl","warp-dissolve","fan-out","peel-off","spin-clockwise","glass-cutting","pink-avalanche"]},"durationMs":{"type":"integer","minimum":100,"maximum":1500}},"required":["op","type"],"additionalProperties":false},{"description":"Turn captions on or off, for the whole video or one scene.","type":"object","properties":{"op":{"type":"string","const":"set_captions"},"enabled":{"type":"boolean"},"clipId":{"description":"One scene only. Leave it out for the whole video.","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"}},"required":["op","enabled"],"additionalProperties":false},{"description":"Correct what a scene's caption says (a misheard word, a name). The voice is not re-recorded.","type":"object","properties":{"op":{"type":"string","const":"set_caption_text"},"clipId":{"description":"The scene whose caption to correct.","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"},"text":{"type":"string","minLength":1,"maxLength":1200}},"required":["op","clipId","text"],"additionalProperties":false},{"description":"Change the caption look, a colour look, the speed of the whole video, or (Video Editor projects) the frame shape.","type":"object","properties":{"op":{"type":"string","const":"set_style"},"captionStyle":{"description":"How the words appear as they are spoken.","type":"string","enum":["classic","color-only","scale-up","typewriter","progressive","karaoke","bounce","outline","background","shadow-pop","pop-color","neon","underline","gradient","boxed","glow"]},"captionFont":{"type":"string","enum":["Montserrat","BebasNeue","Anton","LeagueSpartan"]},"captionPosition":{"type":"string","enum":["top","upper-third","center","lower-third","bottom"]},"captionColor":{"description":"Caption text colour, like #FFFFFF.","type":"string","pattern":"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"},"captionHighlightColor":{"description":"Colour of the word being spoken.","type":"string","pattern":"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"},"captionSize":{"description":"Caption size in pixels.","type":"integer","minimum":24,"maximum":120},"captionBackground":{"description":"A dark plate behind the captions.","type":"boolean"},"captionBackgroundOpacity":{"type":"number","minimum":0,"maximum":1},"captionWordsOnScreen":{"description":"Words shown at once (Classic and Boxed card styles).","type":"number","enum":[2,3,4]},"captionTimingMs":{"description":"Show each word this much earlier (negative) or later.","type":"integer","minimum":-1000,"maximum":1000},"colorGrade":{"description":"A colour look for pictures and videos. none removes it.","type":"string","enum":["none","horror-red","cold-blue","warm-amber","desaturated","high-contrast","dark-moody","sickly-green","neon-purple","sepia","night-vision"]},"colorGradeClipIds":{"description":"Which clips get the colour look (default: every scene with a picture or video).","minItems":1,"maxItems":200,"type":"array","items":{"description":"A clip id from get.","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"}},"videoSpeed":{"description":"One speed for the whole video, voice and music included (0.5 to 2). Slower plays longer: at 0.5 a 1:00 video plays 2:00, and it must still fit the longest video the product makes.","type":"number","minimum":0.5,"maximum":2},"frameShape":{"description":"Video Editor projects only: the frame, 9:16 (tall), 16:9 (wide) or 1:1 (square). Every clip is fitted into the new frame.","type":"string","enum":["9:16","16:9","1:1"]}},"required":["op"],"additionalProperties":false},{"description":"Put a marker on the timeline (a note for yourself; not shown in the video).","type":"object","properties":{"op":{"type":"string","const":"add_marker"},"at":{"description":"A time: a number is milliseconds from the start of the video; text is read the way a person says it. Times can be \"3:36\", \"216s\", \"1m 5s\", \"2s into scene 3\", \"the start of scene 2\", \"the end of scene 4\", \"the middle of scene 2\" or \"when she says 'money'\". Ranges can be \"3:36 to 3:52\", \"3:36-3:52\", \"2s into scene 3 for 4 seconds\", \"scene 2\" or \"the last 5 seconds\".","anyOf":[{"type":"integer","minimum":0,"maximum":21600000},{"type":"string","minLength":1,"maxLength":200}]},"label":{"type":"string","maxLength":80}},"required":["op","at"],"additionalProperties":false},{"description":"Remove a marker.","type":"object","properties":{"op":{"type":"string","const":"remove_marker"},"markerId":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[A-Za-z0-9_.:-]+$"}},"required":["op","markerId"],"additionalProperties":false}]}}},"required":["expectedRevision","operations"],"additionalProperties":false},"example":{"expectedRevision":4,"operations":[{"op":"trim","clipId":"clp_k3x9a2_s_1","edge":"end","at":"0:03"},{"op":"add_text","text":"Wait for it","at":"the start of scene 2","position":"top"}]}}}},"parameters":[{"name":"product","in":"path","required":true,"schema":{"description":"Which product the video belongs to: v3 (a V3 cinematic story), studio (a Studio 2.0 video) or editor (a Video Editor project, made with autoclips_editor create).","type":"string","enum":["v3","studio","editor"]},"description":"Which product the video belongs to: v3 (a V3 cinematic story), studio (a Studio 2.0 video) or editor (a Video Editor project, made with autoclips_editor create).","example":"v3"},{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Video Editor project id (edit_…).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Video Editor project id (edit_…).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"revision":{"description":"The timeline's revision now. Use it as expectedRevision next time.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"saved":{"type":"boolean"},"changes":{"description":"What changed, in plain words.","type":"array","items":{"type":"string"}},"warnings":{"description":"Things the downloaded video cannot show, if any.","type":"array","items":{"type":"string"}},"undo":{"description":"Whether undo can take a change back, and how many kept versions it can go back through.","type":"object","properties":{"available":{"type":"boolean"},"versions":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["available","versions"],"additionalProperties":false},"redo":{"description":"Whether redo can put back what an undo took away. A new edit clears it.","type":"object","properties":{"available":{"type":"boolean"},"versions":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["available","versions"],"additionalProperties":false},"skipped":{"description":"Undo or redo only: kept versions that could not be put back (their media left your library, say), so they were removed and the next one was used.","type":"array","items":{"type":"object","properties":{"revision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reason":{"type":"string"}},"required":["revision","reason"],"additionalProperties":false}},"timeline":{"type":"object","properties":{"product":{"type":"string","enum":["v3","studio","editor"]},"projectId":{"type":"string"},"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"cuts":{"description":"Studio 2.0: every cut of the project that opens in the editor.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"hasEdits":{"type":"boolean"}},"required":["id","label","hasEdits"],"additionalProperties":false}},"revision":{"description":"Send this as expectedRevision with your next edit.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasSavedEdits":{"type":"boolean"},"title":{"type":"string"},"aspect":{"type":"string"},"durationMs":{"type":"number"},"duration":{"type":"string"},"videoSpeed":{"type":"number"},"tracks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"clips":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"muted":{"type":"boolean"},"hidden":{"type":"boolean"},"locked":{"type":"boolean"}},"required":["id","label","kind","clips"],"additionalProperties":false}},"clips":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"track":{"description":"video, overlay, studio_text, text, sound_effects, audio or music.","type":"string"},"kind":{"description":"image, video, text, studio-text or audio.","type":"string"},"scene":{"description":"Scenes only: its number, counting from 1.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"startMs":{"type":"number"},"endMs":{"type":"number"},"time":{"description":"The same times as \"0:03-0:07\".","type":"string"},"label":{"type":"string"},"text":{"type":"string"},"caption":{"description":"Scenes only: the words spoken in it.","type":"string"},"captionsOff":{"type":"boolean"},"media":{"type":"object","properties":{"kind":{"type":"string"},"url":{"type":"string"}},"required":["kind","url"],"additionalProperties":false},"transitionIn":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"durationMs":{"type":"number"}},"required":["type","name","durationMs"],"additionalProperties":false},"sound":{"description":"What set_clip_sound can change, as it is now.","type":"object","properties":{"on":{"type":"boolean"},"volumeDb":{"description":"Volume in dB, 0 as recorded. On music that dips under the narrator's words, the level between the lines (underVoiceDb is the level under them).","type":"number"},"fadeInMs":{"type":"number"},"fadeOutMs":{"type":"number"},"dipUnderVoice":{"description":"Music only: it really is lowered while the narrator speaks, as the video plays it. False when its dip is off, on a video with no narrator, and on older V3 music (made before 2026-10-05) that does not follow the narrator's words: that plays at a steady volumeDb under the voice, though the editor shows its dip switched on, and its note says so.","type":"boolean"},"dipUnderClipSound":{"description":"Music only: it is also lowered under talking recorded in the videos.","type":"boolean"},"dipDb":{"description":"Music only: how far it dips (dB), when it dips.","type":"number"},"underVoiceDb":{"description":"Music that dips under the narrator only: its level under the voice (volumeDb + dipDb).","type":"number"},"note":{"description":"Older music that plays at a steady level under the narrator says so here, and how to make it dip.","type":"string"}},"required":["on","volumeDb","fadeInMs","fadeOutMs"],"additionalProperties":false},"visibleArea":{"description":"Scenes only, when reframe moved it off the middle: which part of the picture shows where it is not the frame's shape.","type":"object","properties":{"x":{"description":"0 left edge, 50 middle, 100 right edge.","type":"number"},"y":{"description":"0 top, 50 middle, 100 bottom.","type":"number"}},"required":["x","y"],"additionalProperties":false},"sfxId":{"type":"string"},"musicId":{"description":"Music only: the track it came from (an id from the music action).","type":"string"},"warning":{"description":"A popular song: AutoClips does not license it.","type":"string"},"studio":{"description":"Studio 2.0 texts only: what set_studio_text_style can change, as it is now.","type":"object","properties":{"kind":{"description":"title, message (a chat bubble), label (a pill) or end_card.","type":"string","enum":["title","end_card","message","label"]},"words":{"description":"Its words, counting from 0: what wordColors in set_studio_text_style points at.","type":"array","items":{"type":"string"}},"side":{"description":"A chat message only: incoming (sent by them, left) or outgoing (sent by me, right).","type":"string","enum":["incoming","outgoing"]},"sender":{"description":"A chat message only: its name. The video shows the name only on a bubble sent by them. A bubble sent by me keeps the name it had, but the video shows none (its note says so). \"\" is no name.","type":"string"},"note":{"description":"A chat bubble sent by me that kept a name: says the video does not show that name.","type":"string"},"look":{"type":"object","properties":{"font":{"type":"string"},"color":{"type":"string"},"background":{"type":"string"},"size":{"description":"Percent of the kind's usual size.","type":"number"},"x":{"description":"Percent across the frame; null is its usual place.","anyOf":[{"type":"number"},{"type":"null"}]},"y":{"description":"Percent down the frame; null is its usual place.","anyOf":[{"type":"number"},{"type":"null"}]},"icon":{"type":"boolean"},"wordColors":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"color":{"type":"string"}},"required":["index","color"],"additionalProperties":false}},"custom":{"description":"True when anything differs from the kind's default look.","type":"boolean"}},"required":["font","color","size","x","y","wordColors","custom"],"additionalProperties":false}},"required":["kind","words","look"],"additionalProperties":false},"hidden":{"type":"boolean"},"locked":{"type":"boolean"}},"required":["id","track","kind","startMs","endMs","time","label"],"additionalProperties":false}},"clipsShown":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clipsTotal":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"trimmed":{"anyOf":[{"type":"string"},{"type":"null"}]},"captions":{"type":"object","properties":{"enabled":{"type":"boolean"},"style":{"type":"string"},"font":{"type":"string"},"position":{"type":"string"},"size":{"type":"number"},"color":{"type":"string"},"highlightColor":{"type":"string"},"background":{"type":"boolean"},"wordsOnScreen":{"type":"number"},"scenesWithWords":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"scenesOff":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["enabled","style","font","position","size","color","highlightColor","background","wordsOnScreen","scenesWithWords","scenesOff"],"additionalProperties":false},"markers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"atMs":{"type":"number"},"at":{"type":"string"},"label":{"type":"string"}},"required":["id","atMs","at","label"],"additionalProperties":false}},"render":{"anyOf":[{"type":"object","properties":{"status":{"description":"idle, queued, rendering, finishing, completed, failed or cancelled.","type":"string"},"progress":{"type":"number"},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"description":"The finished video, once completed.","anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"canCancel":{"type":"boolean"},"stale":{"description":"True when the render stopped reporting for a while; asking again re-checks it with the render service.","type":"boolean"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastVideo":{"description":"The last video the editor finished, and which revision it was made from.","anyOf":[{"type":"object","properties":{"videoUrl":{"type":"string"},"revision":{"anyOf":[{"type":"number"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["videoUrl","revision","finishedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["status","progress","stage","videoUrl","error","canCancel","stale","startedAt","lastVideo"],"additionalProperties":false},{"type":"null"}]},"links":{"type":"object","properties":{"editor":{"type":"string"}},"required":["editor"],"additionalProperties":false}},"required":["product","projectId","variantId","revision","hasSavedEdits","title","aspect","durationMs","duration","videoSpeed","tracks","clips","clipsShown","clipsTotal","trimmed","captions","markers","render","links"],"additionalProperties":false}},"required":["revision","variantId","saved","changes","warnings","undo","timeline"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"revision":5,"variantId":null,"saved":true,"changes":["Trimmed the end of scene 1: it now runs 0:00 to 0:03 (3 seconds). Everything after it moved to match.","Added text \"Wait for it\" at 0:03-0:07, clip clp_1k9x2mq.","The video is now 0:08 long (it was 0:09)."],"warnings":[],"undo":{"available":true,"versions":3},"redo":{"available":false,"versions":0},"timeline":{"product":"v3","projectId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","variantId":null,"revision":5,"hasSavedEdits":true,"title":"The lighthouse keeper","aspect":"9:16","durationMs":8000,"duration":"0:08","videoSpeed":1,"tracks":[{"id":"video","label":"Video","kind":"video","clips":2},{"id":"overlay","label":"Overlay","kind":"video","clips":0},{"id":"text","label":"Text","kind":"text","clips":0},{"id":"sound_effects","label":"Sound effects","kind":"audio","clips":1},{"id":"audio","label":"Audio","kind":"audio","clips":0},{"id":"music","label":"Music","kind":"audio","clips":1}],"clips":[{"id":"clp_k3x9a2_s_1","track":"video","kind":"image","scene":1,"startMs":0,"endMs":4000,"time":"0:00-0:04","label":"Every night he climbed","caption":"Every night he climbed the stairs","media":{"kind":"image","url":"https://media.autoclips.app/generated-images/lamp.png"}},{"id":"clp_k3x9a2_s_2","track":"video","kind":"image","scene":2,"startMs":4000,"endMs":9000,"time":"0:04-0:09","label":"Until the door creaked","caption":"Until the door creaked open","transitionIn":{"type":"mix","name":"Mix","durationMs":600},"media":{"kind":"image","url":"https://media.autoclips.app/generated-images/door.png"}},{"id":"clp_k3x9a2_fx_1","track":"sound_effects","kind":"audio","startMs":5200,"endMs":8200,"time":"0:05.2-0:08.2","label":"Creak Door Slow","sfxId":"creak-door-slow","media":{"kind":"audio","url":"https://media.autoclips.app/sound-effects/v3/horror/creak-door-slow.mp3"},"sound":{"on":true,"volumeDb":0,"fadeInMs":0,"fadeOutMs":0}},{"id":"clp_k3x9a2_mu_1","track":"music","kind":"audio","startMs":0,"endMs":9000,"time":"0:00-0:09","label":"Night Tide","sound":{"on":true,"volumeDb":-14,"fadeInMs":1500,"fadeOutMs":3000,"dipUnderVoice":true,"dipUnderClipSound":false,"dipDb":-6,"underVoiceDb":-20}}],"clipsShown":4,"clipsTotal":4,"trimmed":null,"captions":{"enabled":true,"style":"glow","font":"BebasNeue","position":"lower-third","size":68,"color":"#FFFFFF","highlightColor":"#FF2222","background":false,"wordsOnScreen":3,"scenesWithWords":2,"scenesOff":0},"markers":[],"render":{"status":"completed","progress":100,"stage":null,"videoUrl":"https://media.autoclips.app/videos/v3_cinematic_lighthouse.mp4","error":null,"canCancel":false,"stale":false,"startedAt":null,"lastVideo":null},"links":{"editor":"https://app.autoclips.app/editor/b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/timeline/{product}/{projectId}/redo":{"post":{"operationId":"shared_timeline_redo","summary":"Take back the last undo, until the next edit: the timeline goes back to how it was before that undo, saved as a new revision.","description":"Puts back the timeline as the newest undo made through the API found it, including any website editor changes that undo took away, saved as a new revision. Call it again after several undos to go forward again; undo takes a redo back. A new edit made through the API clears redo, like any editor: what earlier undos took away can then no longer be put back. Changes saved in the website editor since the undo do not clear it; redo replaces them, but keeps them first, so undo brings them back. Needs expectedRevision, like edit. Free.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.timeline.redo","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_timeline action=redo","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"variantId":{"description":"Studio 2.0 only: which cut (finished video) to work on. Leave it out for the first cut; get lists every cut under \"cuts\". Send back the variantId you read, so every call works on the same cut.","type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.-]*$"},"expectedRevision":{"description":"The revision you read with get (or got back from your last edit). If the timeline changed since, nothing is saved and the answer is revision_conflict: read it again and redo the edit.","type":"integer","minimum":0,"maximum":1000000000}},"required":["expectedRevision"],"additionalProperties":false},"example":{"expectedRevision":6}}}},"parameters":[{"name":"product","in":"path","required":true,"schema":{"description":"Which product the video belongs to: v3 (a V3 cinematic story), studio (a Studio 2.0 video) or editor (a Video Editor project, made with autoclips_editor create).","type":"string","enum":["v3","studio","editor"]},"description":"Which product the video belongs to: v3 (a V3 cinematic story), studio (a Studio 2.0 video) or editor (a Video Editor project, made with autoclips_editor create).","example":"v3"},{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Video Editor project id (edit_…).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Video Editor project id (edit_…).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"revision":{"description":"The timeline's revision now. Use it as expectedRevision next time.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"saved":{"type":"boolean"},"changes":{"description":"What changed, in plain words.","type":"array","items":{"type":"string"}},"warnings":{"description":"Things the downloaded video cannot show, if any.","type":"array","items":{"type":"string"}},"undo":{"description":"Whether undo can take a change back, and how many kept versions it can go back through.","type":"object","properties":{"available":{"type":"boolean"},"versions":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["available","versions"],"additionalProperties":false},"redo":{"description":"Whether redo can put back what an undo took away. A new edit clears it.","type":"object","properties":{"available":{"type":"boolean"},"versions":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["available","versions"],"additionalProperties":false},"skipped":{"description":"Undo or redo only: kept versions that could not be put back (their media left your library, say), so they were removed and the next one was used.","type":"array","items":{"type":"object","properties":{"revision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reason":{"type":"string"}},"required":["revision","reason"],"additionalProperties":false}},"timeline":{"type":"object","properties":{"product":{"type":"string","enum":["v3","studio","editor"]},"projectId":{"type":"string"},"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"cuts":{"description":"Studio 2.0: every cut of the project that opens in the editor.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"hasEdits":{"type":"boolean"}},"required":["id","label","hasEdits"],"additionalProperties":false}},"revision":{"description":"Send this as expectedRevision with your next edit.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasSavedEdits":{"type":"boolean"},"title":{"type":"string"},"aspect":{"type":"string"},"durationMs":{"type":"number"},"duration":{"type":"string"},"videoSpeed":{"type":"number"},"tracks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"clips":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"muted":{"type":"boolean"},"hidden":{"type":"boolean"},"locked":{"type":"boolean"}},"required":["id","label","kind","clips"],"additionalProperties":false}},"clips":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"track":{"description":"video, overlay, studio_text, text, sound_effects, audio or music.","type":"string"},"kind":{"description":"image, video, text, studio-text or audio.","type":"string"},"scene":{"description":"Scenes only: its number, counting from 1.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"startMs":{"type":"number"},"endMs":{"type":"number"},"time":{"description":"The same times as \"0:03-0:07\".","type":"string"},"label":{"type":"string"},"text":{"type":"string"},"caption":{"description":"Scenes only: the words spoken in it.","type":"string"},"captionsOff":{"type":"boolean"},"media":{"type":"object","properties":{"kind":{"type":"string"},"url":{"type":"string"}},"required":["kind","url"],"additionalProperties":false},"transitionIn":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"durationMs":{"type":"number"}},"required":["type","name","durationMs"],"additionalProperties":false},"sound":{"description":"What set_clip_sound can change, as it is now.","type":"object","properties":{"on":{"type":"boolean"},"volumeDb":{"description":"Volume in dB, 0 as recorded. On music that dips under the narrator's words, the level between the lines (underVoiceDb is the level under them).","type":"number"},"fadeInMs":{"type":"number"},"fadeOutMs":{"type":"number"},"dipUnderVoice":{"description":"Music only: it really is lowered while the narrator speaks, as the video plays it. False when its dip is off, on a video with no narrator, and on older V3 music (made before 2026-10-05) that does not follow the narrator's words: that plays at a steady volumeDb under the voice, though the editor shows its dip switched on, and its note says so.","type":"boolean"},"dipUnderClipSound":{"description":"Music only: it is also lowered under talking recorded in the videos.","type":"boolean"},"dipDb":{"description":"Music only: how far it dips (dB), when it dips.","type":"number"},"underVoiceDb":{"description":"Music that dips under the narrator only: its level under the voice (volumeDb + dipDb).","type":"number"},"note":{"description":"Older music that plays at a steady level under the narrator says so here, and how to make it dip.","type":"string"}},"required":["on","volumeDb","fadeInMs","fadeOutMs"],"additionalProperties":false},"visibleArea":{"description":"Scenes only, when reframe moved it off the middle: which part of the picture shows where it is not the frame's shape.","type":"object","properties":{"x":{"description":"0 left edge, 50 middle, 100 right edge.","type":"number"},"y":{"description":"0 top, 50 middle, 100 bottom.","type":"number"}},"required":["x","y"],"additionalProperties":false},"sfxId":{"type":"string"},"musicId":{"description":"Music only: the track it came from (an id from the music action).","type":"string"},"warning":{"description":"A popular song: AutoClips does not license it.","type":"string"},"studio":{"description":"Studio 2.0 texts only: what set_studio_text_style can change, as it is now.","type":"object","properties":{"kind":{"description":"title, message (a chat bubble), label (a pill) or end_card.","type":"string","enum":["title","end_card","message","label"]},"words":{"description":"Its words, counting from 0: what wordColors in set_studio_text_style points at.","type":"array","items":{"type":"string"}},"side":{"description":"A chat message only: incoming (sent by them, left) or outgoing (sent by me, right).","type":"string","enum":["incoming","outgoing"]},"sender":{"description":"A chat message only: its name. The video shows the name only on a bubble sent by them. A bubble sent by me keeps the name it had, but the video shows none (its note says so). \"\" is no name.","type":"string"},"note":{"description":"A chat bubble sent by me that kept a name: says the video does not show that name.","type":"string"},"look":{"type":"object","properties":{"font":{"type":"string"},"color":{"type":"string"},"background":{"type":"string"},"size":{"description":"Percent of the kind's usual size.","type":"number"},"x":{"description":"Percent across the frame; null is its usual place.","anyOf":[{"type":"number"},{"type":"null"}]},"y":{"description":"Percent down the frame; null is its usual place.","anyOf":[{"type":"number"},{"type":"null"}]},"icon":{"type":"boolean"},"wordColors":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"color":{"type":"string"}},"required":["index","color"],"additionalProperties":false}},"custom":{"description":"True when anything differs from the kind's default look.","type":"boolean"}},"required":["font","color","size","x","y","wordColors","custom"],"additionalProperties":false}},"required":["kind","words","look"],"additionalProperties":false},"hidden":{"type":"boolean"},"locked":{"type":"boolean"}},"required":["id","track","kind","startMs","endMs","time","label"],"additionalProperties":false}},"clipsShown":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clipsTotal":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"trimmed":{"anyOf":[{"type":"string"},{"type":"null"}]},"captions":{"type":"object","properties":{"enabled":{"type":"boolean"},"style":{"type":"string"},"font":{"type":"string"},"position":{"type":"string"},"size":{"type":"number"},"color":{"type":"string"},"highlightColor":{"type":"string"},"background":{"type":"boolean"},"wordsOnScreen":{"type":"number"},"scenesWithWords":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"scenesOff":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["enabled","style","font","position","size","color","highlightColor","background","wordsOnScreen","scenesWithWords","scenesOff"],"additionalProperties":false},"markers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"atMs":{"type":"number"},"at":{"type":"string"},"label":{"type":"string"}},"required":["id","atMs","at","label"],"additionalProperties":false}},"render":{"anyOf":[{"type":"object","properties":{"status":{"description":"idle, queued, rendering, finishing, completed, failed or cancelled.","type":"string"},"progress":{"type":"number"},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"description":"The finished video, once completed.","anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"canCancel":{"type":"boolean"},"stale":{"description":"True when the render stopped reporting for a while; asking again re-checks it with the render service.","type":"boolean"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastVideo":{"description":"The last video the editor finished, and which revision it was made from.","anyOf":[{"type":"object","properties":{"videoUrl":{"type":"string"},"revision":{"anyOf":[{"type":"number"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["videoUrl","revision","finishedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["status","progress","stage","videoUrl","error","canCancel","stale","startedAt","lastVideo"],"additionalProperties":false},{"type":"null"}]},"links":{"type":"object","properties":{"editor":{"type":"string"}},"required":["editor"],"additionalProperties":false}},"required":["product","projectId","variantId","revision","hasSavedEdits","title","aspect","durationMs","duration","videoSpeed","tracks","clips","clipsShown","clipsTotal","trimmed","captions","markers","render","links"],"additionalProperties":false}},"required":["revision","variantId","saved","changes","warnings","undo","timeline"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/timeline/{product}/{projectId}/render":{"post":{"operationId":"shared_timeline_render","summary":"Make the new video from the saved timeline (Studio 2.0; not V3 yet). Answers with a job to follow; costs no credits.","description":"Renders the timeline as it is saved now, exactly like the editor's Render button, and answers at once with a job. Follow it with autoclips_jobs get (GET /jobs/{id}); when it succeeds its result has videoUrl. While it runs, a Studio 2.0 job's result names the cut it renders. One render per project at a time: asking again while one runs returns the same job. Rendering costs no credits (the pictures and clips were paid for when they were made); it counts toward the daily limit for new videos and the product's own daily video limit. V3 (product v3) is not rendered here yet: the request is refused (nothing started, no daily limit used) with the two ways to a video, the editor's Render button, or undo back to the cut the video was made with and v3_production render.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.timeline.render","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_timeline action=render","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"variantId":{"description":"Studio 2.0 only: which cut (finished video) to work on. Leave it out for the first cut; get lists every cut under \"cuts\". Send back the variantId you read, so every call works on the same cut.","type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.-]*$"}},"additionalProperties":false},"example":{"variantId":"ver_20260927"}}}},"parameters":[{"name":"product","in":"path","required":true,"schema":{"description":"Which product the video belongs to: v3 (a V3 cinematic story), studio (a Studio 2.0 video) or editor (a Video Editor project, made with autoclips_editor create).","type":"string","enum":["v3","studio","editor"]},"description":"Which product the video belongs to: v3 (a V3 cinematic story), studio (a Studio 2.0 video) or editor (a Video Editor project, made with autoclips_editor create).","example":"studio"},{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Video Editor project id (edit_…).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Video Editor project id (edit_…).","example":"a1b2c3d4-e5f6-4a7b-8c9d-112233445566"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"alreadyRunning":{"type":"boolean"},"revision":{"description":"The revision being rendered.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"render":{"anyOf":[{"type":"object","properties":{"status":{"description":"idle, queued, rendering, finishing, completed, failed or cancelled.","type":"string"},"progress":{"type":"number"},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"description":"The finished video, once completed.","anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"canCancel":{"type":"boolean"},"stale":{"description":"True when the render stopped reporting for a while; asking again re-checks it with the render service.","type":"boolean"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastVideo":{"description":"The last video the editor finished, and which revision it was made from.","anyOf":[{"type":"object","properties":{"videoUrl":{"type":"string"},"revision":{"anyOf":[{"type":"number"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["videoUrl","revision","finishedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["status","progress","stage","videoUrl","error","canCancel","stale","startedAt","lastVideo"],"additionalProperties":false},{"type":"null"}]},"warnings":{"type":"array","items":{"type":"string"}}},"required":["job","alreadyRunning","revision","variantId","render","warnings"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"job":{"id":"job_0192f1a2b3c4d5e6f7a8b9c1","product":"studio","kind":"studio.editor_render","resource":{"type":"project","id":"a1b2c3d4-e5f6-4a7b-8c9d-112233445566"},"status":"queued","step":"waiting for the render service","progress":0,"result":{"cut":"ver_20260927"},"error":null,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","finishedAt":null,"poll_after_seconds":15},"alreadyRunning":false,"revision":3,"variantId":"ver_20260927","render":{"status":"queued","progress":0,"stage":"submit","videoUrl":null,"error":null,"canCancel":true,"stale":false,"startedAt":"2026-09-28T10:00:00.000Z","lastVideo":null},"warnings":[]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"shared_timeline_render_status","summary":"See whether this video is rendering, how far along it is, and the link to the last finished video.","description":"The editor's render state for this timeline: status, percent done, the finished video link, and the last video made. A render that stopped reporting is re-checked with the render service. For a render you started through the API, following its job does the same.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.timeline.render_status","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_timeline action=render_status","parameters":[{"name":"product","in":"path","required":true,"schema":{"description":"Which product the video belongs to: v3 (a V3 cinematic story), studio (a Studio 2.0 video) or editor (a Video Editor project, made with autoclips_editor create).","type":"string","enum":["v3","studio","editor"]},"description":"Which product the video belongs to: v3 (a V3 cinematic story), studio (a Studio 2.0 video) or editor (a Video Editor project, made with autoclips_editor create).","example":"v3"},{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Video Editor project id (edit_…).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Video Editor project id (edit_…).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},{"name":"variantId","in":"query","required":false,"schema":{"description":"Studio 2.0 only: which cut (finished video) to work on. Leave it out for the first cut; get lists every cut under \"cuts\". Send back the variantId you read, so every call works on the same cut.","type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.-]*$"},"description":"Studio 2.0 only: which cut (finished video) to work on. Leave it out for the first cut; get lists every cut under \"cuts\". Send back the variantId you read, so every call works on the same cut."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"render":{"type":"object","properties":{"status":{"description":"idle, queued, rendering, finishing, completed, failed or cancelled.","type":"string"},"progress":{"type":"number"},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"description":"The finished video, once completed.","anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"canCancel":{"type":"boolean"},"stale":{"description":"True when the render stopped reporting for a while; asking again re-checks it with the render service.","type":"boolean"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastVideo":{"description":"The last video the editor finished, and which revision it was made from.","anyOf":[{"type":"object","properties":{"videoUrl":{"type":"string"},"revision":{"anyOf":[{"type":"number"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["videoUrl","revision","finishedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["status","progress","stage","videoUrl","error","canCancel","stale","startedAt","lastVideo"],"additionalProperties":false},"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["render","variantId"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/timeline/{product}/{projectId}/render/cancel":{"post":{"operationId":"shared_timeline_render_cancel","summary":"Stop the render that is running for this video. The timeline and earlier videos stay as they are.","description":"Stops the editor render running for this timeline, like the editor's Cancel button. Nothing else changes; its job ends as canceled. Answers conflict when nothing is rendering.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.timeline.render_cancel","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_timeline action=render_cancel","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"variantId":{"description":"Studio 2.0 only: which cut (finished video) to work on. Leave it out for the first cut; get lists every cut under \"cuts\". Send back the variantId you read, so every call works on the same cut.","type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.-]*$"}},"additionalProperties":false},"example":{"variantId":"ver_20260927"}}}},"parameters":[{"name":"product","in":"path","required":true,"schema":{"description":"Which product the video belongs to: v3 (a V3 cinematic story), studio (a Studio 2.0 video) or editor (a Video Editor project, made with autoclips_editor create).","type":"string","enum":["v3","studio","editor"]},"description":"Which product the video belongs to: v3 (a V3 cinematic story), studio (a Studio 2.0 video) or editor (a Video Editor project, made with autoclips_editor create).","example":"studio"},{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Video Editor project id (edit_…).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Video Editor project id (edit_…).","example":"a1b2c3d4-e5f6-4a7b-8c9d-112233445566"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"canceled":{"type":"boolean"},"render":{"anyOf":[{"type":"object","properties":{"status":{"description":"idle, queued, rendering, finishing, completed, failed or cancelled.","type":"string"},"progress":{"type":"number"},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"description":"The finished video, once completed.","anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"canCancel":{"type":"boolean"},"stale":{"description":"True when the render stopped reporting for a while; asking again re-checks it with the render service.","type":"boolean"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastVideo":{"description":"The last video the editor finished, and which revision it was made from.","anyOf":[{"type":"object","properties":{"videoUrl":{"type":"string"},"revision":{"anyOf":[{"type":"number"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["videoUrl","revision","finishedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["status","progress","stage","videoUrl","error","canCancel","stale","startedAt","lastVideo"],"additionalProperties":false},{"type":"null"}]}},"required":["canceled","render"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"canceled":true,"render":{"status":"cancelled","progress":40,"stage":"render","videoUrl":null,"error":"You cancelled this render.","canCancel":false,"stale":false,"startedAt":"2026-09-28T10:00:00.000Z","lastVideo":null}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/timeline/{product}/{projectId}/transcribe":{"post":{"operationId":"shared_timeline_transcribe","summary":"Captions from a video scene's own speech: listen to one clip, put its words on the timeline as captions, saved as a new revision.","description":"Listens to one video scene (a clip on the video row whose video has speech, like a Studio 2.0 clip with voices) and puts the words it hears on that scene as its captions, timed to the speech, exactly like the editor's Generate captions. The scene's own sound is switched on (captions follow what is heard), captions are switched on for the video if they were off, and the caption language follows the language heard unless someone chose one. Saved as a new revision like edit: send expectedRevision, and undo takes it back. A timeline nobody has saved yet is first saved unchanged (the answer says so). One scene per call: to caption a whole video, call it once for each video scene, sending the language the first answer gave. A clip with nobody speaking answers no_speech and changes nothing. Free, and counts toward the daily limit of free AI helpers: one per call, plus one for each started 10 MB or 5 minutes of the scene's video file beyond the first, because the whole file is listened to.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.timeline.transcribe","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_timeline action=transcribe","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"variantId":{"description":"Studio 2.0 only: which cut (finished video) to work on. Leave it out for the first cut; get lists every cut under \"cuts\". Send back the variantId you read, so every call works on the same cut.","type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.-]*$"},"expectedRevision":{"description":"The revision you read with get (or got back from your last edit). If the timeline changed since, nothing is saved and the answer is revision_conflict: read it again and redo the edit.","type":"integer","minimum":0,"maximum":1000000000},"clipId":{"description":"The video scene to caption: a clip id on the video row, from get.","type":"string","minLength":1,"maxLength":120,"pattern":"^(?!(?:constructor|__proto__|prototype)$)[A-Za-z0-9_.:-]+$"},"language":{"description":"The language spoken in the clip, as a code like en, es, hi (or auto to detect it). Leave it out to use the video's language, or detect it. When captioning several scenes, send the language the first answer gave.","type":"string","pattern":"^(auto|[a-z]{2,3})$"}},"required":["expectedRevision","clipId"],"additionalProperties":false},"example":{"variantId":"ver_20260927","expectedRevision":3,"clipId":"clp_k3x9a2_s_1"}}}},"parameters":[{"name":"product","in":"path","required":true,"schema":{"description":"Which product the video belongs to: v3 (a V3 cinematic story), studio (a Studio 2.0 video) or editor (a Video Editor project, made with autoclips_editor create).","type":"string","enum":["v3","studio","editor"]},"description":"Which product the video belongs to: v3 (a V3 cinematic story), studio (a Studio 2.0 video) or editor (a Video Editor project, made with autoclips_editor create).","example":"studio"},{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Video Editor project id (edit_…).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Video Editor project id (edit_…).","example":"a1b2c3d4-e5f6-4a7b-8c9d-112233445566"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"revision":{"description":"The timeline's revision now. Use it as expectedRevision next time.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"saved":{"type":"boolean"},"changes":{"description":"What changed, in plain words.","type":"array","items":{"type":"string"}},"warnings":{"description":"Things the downloaded video cannot show, if any.","type":"array","items":{"type":"string"}},"undo":{"description":"Whether undo can take a change back, and how many kept versions it can go back through.","type":"object","properties":{"available":{"type":"boolean"},"versions":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["available","versions"],"additionalProperties":false},"redo":{"description":"Whether redo can put back what an undo took away. A new edit clears it.","type":"object","properties":{"available":{"type":"boolean"},"versions":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["available","versions"],"additionalProperties":false},"skipped":{"description":"Undo or redo only: kept versions that could not be put back (their media left your library, say), so they were removed and the next one was used.","type":"array","items":{"type":"object","properties":{"revision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reason":{"type":"string"}},"required":["revision","reason"],"additionalProperties":false}},"timeline":{"type":"object","properties":{"product":{"type":"string","enum":["v3","studio","editor"]},"projectId":{"type":"string"},"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"cuts":{"description":"Studio 2.0: every cut of the project that opens in the editor.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"hasEdits":{"type":"boolean"}},"required":["id","label","hasEdits"],"additionalProperties":false}},"revision":{"description":"Send this as expectedRevision with your next edit.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasSavedEdits":{"type":"boolean"},"title":{"type":"string"},"aspect":{"type":"string"},"durationMs":{"type":"number"},"duration":{"type":"string"},"videoSpeed":{"type":"number"},"tracks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"clips":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"muted":{"type":"boolean"},"hidden":{"type":"boolean"},"locked":{"type":"boolean"}},"required":["id","label","kind","clips"],"additionalProperties":false}},"clips":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"track":{"description":"video, overlay, studio_text, text, sound_effects, audio or music.","type":"string"},"kind":{"description":"image, video, text, studio-text or audio.","type":"string"},"scene":{"description":"Scenes only: its number, counting from 1.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"startMs":{"type":"number"},"endMs":{"type":"number"},"time":{"description":"The same times as \"0:03-0:07\".","type":"string"},"label":{"type":"string"},"text":{"type":"string"},"caption":{"description":"Scenes only: the words spoken in it.","type":"string"},"captionsOff":{"type":"boolean"},"media":{"type":"object","properties":{"kind":{"type":"string"},"url":{"type":"string"}},"required":["kind","url"],"additionalProperties":false},"transitionIn":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"durationMs":{"type":"number"}},"required":["type","name","durationMs"],"additionalProperties":false},"sound":{"description":"What set_clip_sound can change, as it is now.","type":"object","properties":{"on":{"type":"boolean"},"volumeDb":{"description":"Volume in dB, 0 as recorded. On music that dips under the narrator's words, the level between the lines (underVoiceDb is the level under them).","type":"number"},"fadeInMs":{"type":"number"},"fadeOutMs":{"type":"number"},"dipUnderVoice":{"description":"Music only: it really is lowered while the narrator speaks, as the video plays it. False when its dip is off, on a video with no narrator, and on older V3 music (made before 2026-10-05) that does not follow the narrator's words: that plays at a steady volumeDb under the voice, though the editor shows its dip switched on, and its note says so.","type":"boolean"},"dipUnderClipSound":{"description":"Music only: it is also lowered under talking recorded in the videos.","type":"boolean"},"dipDb":{"description":"Music only: how far it dips (dB), when it dips.","type":"number"},"underVoiceDb":{"description":"Music that dips under the narrator only: its level under the voice (volumeDb + dipDb).","type":"number"},"note":{"description":"Older music that plays at a steady level under the narrator says so here, and how to make it dip.","type":"string"}},"required":["on","volumeDb","fadeInMs","fadeOutMs"],"additionalProperties":false},"visibleArea":{"description":"Scenes only, when reframe moved it off the middle: which part of the picture shows where it is not the frame's shape.","type":"object","properties":{"x":{"description":"0 left edge, 50 middle, 100 right edge.","type":"number"},"y":{"description":"0 top, 50 middle, 100 bottom.","type":"number"}},"required":["x","y"],"additionalProperties":false},"sfxId":{"type":"string"},"musicId":{"description":"Music only: the track it came from (an id from the music action).","type":"string"},"warning":{"description":"A popular song: AutoClips does not license it.","type":"string"},"studio":{"description":"Studio 2.0 texts only: what set_studio_text_style can change, as it is now.","type":"object","properties":{"kind":{"description":"title, message (a chat bubble), label (a pill) or end_card.","type":"string","enum":["title","end_card","message","label"]},"words":{"description":"Its words, counting from 0: what wordColors in set_studio_text_style points at.","type":"array","items":{"type":"string"}},"side":{"description":"A chat message only: incoming (sent by them, left) or outgoing (sent by me, right).","type":"string","enum":["incoming","outgoing"]},"sender":{"description":"A chat message only: its name. The video shows the name only on a bubble sent by them. A bubble sent by me keeps the name it had, but the video shows none (its note says so). \"\" is no name.","type":"string"},"note":{"description":"A chat bubble sent by me that kept a name: says the video does not show that name.","type":"string"},"look":{"type":"object","properties":{"font":{"type":"string"},"color":{"type":"string"},"background":{"type":"string"},"size":{"description":"Percent of the kind's usual size.","type":"number"},"x":{"description":"Percent across the frame; null is its usual place.","anyOf":[{"type":"number"},{"type":"null"}]},"y":{"description":"Percent down the frame; null is its usual place.","anyOf":[{"type":"number"},{"type":"null"}]},"icon":{"type":"boolean"},"wordColors":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"color":{"type":"string"}},"required":["index","color"],"additionalProperties":false}},"custom":{"description":"True when anything differs from the kind's default look.","type":"boolean"}},"required":["font","color","size","x","y","wordColors","custom"],"additionalProperties":false}},"required":["kind","words","look"],"additionalProperties":false},"hidden":{"type":"boolean"},"locked":{"type":"boolean"}},"required":["id","track","kind","startMs","endMs","time","label"],"additionalProperties":false}},"clipsShown":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clipsTotal":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"trimmed":{"anyOf":[{"type":"string"},{"type":"null"}]},"captions":{"type":"object","properties":{"enabled":{"type":"boolean"},"style":{"type":"string"},"font":{"type":"string"},"position":{"type":"string"},"size":{"type":"number"},"color":{"type":"string"},"highlightColor":{"type":"string"},"background":{"type":"boolean"},"wordsOnScreen":{"type":"number"},"scenesWithWords":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"scenesOff":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["enabled","style","font","position","size","color","highlightColor","background","wordsOnScreen","scenesWithWords","scenesOff"],"additionalProperties":false},"markers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"atMs":{"type":"number"},"at":{"type":"string"},"label":{"type":"string"}},"required":["id","atMs","at","label"],"additionalProperties":false}},"render":{"anyOf":[{"type":"object","properties":{"status":{"description":"idle, queued, rendering, finishing, completed, failed or cancelled.","type":"string"},"progress":{"type":"number"},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"description":"The finished video, once completed.","anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"canCancel":{"type":"boolean"},"stale":{"description":"True when the render stopped reporting for a while; asking again re-checks it with the render service.","type":"boolean"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastVideo":{"description":"The last video the editor finished, and which revision it was made from.","anyOf":[{"type":"object","properties":{"videoUrl":{"type":"string"},"revision":{"anyOf":[{"type":"number"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["videoUrl","revision","finishedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["status","progress","stage","videoUrl","error","canCancel","stale","startedAt","lastVideo"],"additionalProperties":false},{"type":"null"}]},"links":{"type":"object","properties":{"editor":{"type":"string"}},"required":["editor"],"additionalProperties":false}},"required":["product","projectId","variantId","revision","hasSavedEdits","title","aspect","durationMs","duration","videoSpeed","tracks","clips","clipsShown","clipsTotal","trimmed","captions","markers","render","links"],"additionalProperties":false},"status":{"description":"ready: captions were added. no_speech: nobody speaks in the clip, so nothing was added.","type":"string","enum":["ready","no_speech"]},"clipId":{"type":"string"},"scene":{"description":"The scene's number, counting from 1.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"language":{"description":"The language heard (a code like en). Send it with the next scenes of the same video.","anyOf":[{"type":"string"},{"type":"null"}]},"text":{"description":"What was said, as heard.","type":"string"},"words":{"description":"How many words the captions have.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"dailySlots":{"description":"How many of the day's free AI helpers this call counted: one, plus one for each started 10 MB or 5 minutes of the scene's video file beyond the first (the whole file is listened to).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["revision","variantId","saved","changes","warnings","undo","timeline","status","clipId","scene","language","text","words","dailySlots"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/timeline/{product}/{projectId}/undo":{"post":{"operationId":"shared_timeline_undo","summary":"Take back the last edit made through the API: the timeline goes back to how it was, saved as a new revision. redo puts it back again.","description":"Puts back the timeline as it was before the newest edit made through the API (the last 10 are kept), saved as a new revision. Call it again to go further back. Edits made in the website editor are not kept here, so going back also takes back any editor changes made after that API edit; the timeline as undo found it is kept first, so redo puts all of it back, until the next edit made through the API (a new edit clears redo, like any editor). A kept version whose media has since left your media library can no longer be put back: it is skipped and removed, the answer says which, and the next one is used. Needs expectedRevision, like edit. Free.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.timeline.undo","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_timeline action=undo","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"variantId":{"description":"Studio 2.0 only: which cut (finished video) to work on. Leave it out for the first cut; get lists every cut under \"cuts\". Send back the variantId you read, so every call works on the same cut.","type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.-]*$"},"expectedRevision":{"description":"The revision you read with get (or got back from your last edit). If the timeline changed since, nothing is saved and the answer is revision_conflict: read it again and redo the edit.","type":"integer","minimum":0,"maximum":1000000000}},"required":["expectedRevision"],"additionalProperties":false},"example":{"expectedRevision":5}}}},"parameters":[{"name":"product","in":"path","required":true,"schema":{"description":"Which product the video belongs to: v3 (a V3 cinematic story), studio (a Studio 2.0 video) or editor (a Video Editor project, made with autoclips_editor create).","type":"string","enum":["v3","studio","editor"]},"description":"Which product the video belongs to: v3 (a V3 cinematic story), studio (a Studio 2.0 video) or editor (a Video Editor project, made with autoclips_editor create).","example":"v3"},{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Video Editor project id (edit_…).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Video Editor project id (edit_…).","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"revision":{"description":"The timeline's revision now. Use it as expectedRevision next time.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"saved":{"type":"boolean"},"changes":{"description":"What changed, in plain words.","type":"array","items":{"type":"string"}},"warnings":{"description":"Things the downloaded video cannot show, if any.","type":"array","items":{"type":"string"}},"undo":{"description":"Whether undo can take a change back, and how many kept versions it can go back through.","type":"object","properties":{"available":{"type":"boolean"},"versions":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["available","versions"],"additionalProperties":false},"redo":{"description":"Whether redo can put back what an undo took away. A new edit clears it.","type":"object","properties":{"available":{"type":"boolean"},"versions":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["available","versions"],"additionalProperties":false},"skipped":{"description":"Undo or redo only: kept versions that could not be put back (their media left your library, say), so they were removed and the next one was used.","type":"array","items":{"type":"object","properties":{"revision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reason":{"type":"string"}},"required":["revision","reason"],"additionalProperties":false}},"timeline":{"type":"object","properties":{"product":{"type":"string","enum":["v3","studio","editor"]},"projectId":{"type":"string"},"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"cuts":{"description":"Studio 2.0: every cut of the project that opens in the editor.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"hasEdits":{"type":"boolean"}},"required":["id","label","hasEdits"],"additionalProperties":false}},"revision":{"description":"Send this as expectedRevision with your next edit.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasSavedEdits":{"type":"boolean"},"title":{"type":"string"},"aspect":{"type":"string"},"durationMs":{"type":"number"},"duration":{"type":"string"},"videoSpeed":{"type":"number"},"tracks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"clips":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"muted":{"type":"boolean"},"hidden":{"type":"boolean"},"locked":{"type":"boolean"}},"required":["id","label","kind","clips"],"additionalProperties":false}},"clips":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"track":{"description":"video, overlay, studio_text, text, sound_effects, audio or music.","type":"string"},"kind":{"description":"image, video, text, studio-text or audio.","type":"string"},"scene":{"description":"Scenes only: its number, counting from 1.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"startMs":{"type":"number"},"endMs":{"type":"number"},"time":{"description":"The same times as \"0:03-0:07\".","type":"string"},"label":{"type":"string"},"text":{"type":"string"},"caption":{"description":"Scenes only: the words spoken in it.","type":"string"},"captionsOff":{"type":"boolean"},"media":{"type":"object","properties":{"kind":{"type":"string"},"url":{"type":"string"}},"required":["kind","url"],"additionalProperties":false},"transitionIn":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"durationMs":{"type":"number"}},"required":["type","name","durationMs"],"additionalProperties":false},"sound":{"description":"What set_clip_sound can change, as it is now.","type":"object","properties":{"on":{"type":"boolean"},"volumeDb":{"description":"Volume in dB, 0 as recorded. On music that dips under the narrator's words, the level between the lines (underVoiceDb is the level under them).","type":"number"},"fadeInMs":{"type":"number"},"fadeOutMs":{"type":"number"},"dipUnderVoice":{"description":"Music only: it really is lowered while the narrator speaks, as the video plays it. False when its dip is off, on a video with no narrator, and on older V3 music (made before 2026-10-05) that does not follow the narrator's words: that plays at a steady volumeDb under the voice, though the editor shows its dip switched on, and its note says so.","type":"boolean"},"dipUnderClipSound":{"description":"Music only: it is also lowered under talking recorded in the videos.","type":"boolean"},"dipDb":{"description":"Music only: how far it dips (dB), when it dips.","type":"number"},"underVoiceDb":{"description":"Music that dips under the narrator only: its level under the voice (volumeDb + dipDb).","type":"number"},"note":{"description":"Older music that plays at a steady level under the narrator says so here, and how to make it dip.","type":"string"}},"required":["on","volumeDb","fadeInMs","fadeOutMs"],"additionalProperties":false},"visibleArea":{"description":"Scenes only, when reframe moved it off the middle: which part of the picture shows where it is not the frame's shape.","type":"object","properties":{"x":{"description":"0 left edge, 50 middle, 100 right edge.","type":"number"},"y":{"description":"0 top, 50 middle, 100 bottom.","type":"number"}},"required":["x","y"],"additionalProperties":false},"sfxId":{"type":"string"},"musicId":{"description":"Music only: the track it came from (an id from the music action).","type":"string"},"warning":{"description":"A popular song: AutoClips does not license it.","type":"string"},"studio":{"description":"Studio 2.0 texts only: what set_studio_text_style can change, as it is now.","type":"object","properties":{"kind":{"description":"title, message (a chat bubble), label (a pill) or end_card.","type":"string","enum":["title","end_card","message","label"]},"words":{"description":"Its words, counting from 0: what wordColors in set_studio_text_style points at.","type":"array","items":{"type":"string"}},"side":{"description":"A chat message only: incoming (sent by them, left) or outgoing (sent by me, right).","type":"string","enum":["incoming","outgoing"]},"sender":{"description":"A chat message only: its name. The video shows the name only on a bubble sent by them. A bubble sent by me keeps the name it had, but the video shows none (its note says so). \"\" is no name.","type":"string"},"note":{"description":"A chat bubble sent by me that kept a name: says the video does not show that name.","type":"string"},"look":{"type":"object","properties":{"font":{"type":"string"},"color":{"type":"string"},"background":{"type":"string"},"size":{"description":"Percent of the kind's usual size.","type":"number"},"x":{"description":"Percent across the frame; null is its usual place.","anyOf":[{"type":"number"},{"type":"null"}]},"y":{"description":"Percent down the frame; null is its usual place.","anyOf":[{"type":"number"},{"type":"null"}]},"icon":{"type":"boolean"},"wordColors":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"color":{"type":"string"}},"required":["index","color"],"additionalProperties":false}},"custom":{"description":"True when anything differs from the kind's default look.","type":"boolean"}},"required":["font","color","size","x","y","wordColors","custom"],"additionalProperties":false}},"required":["kind","words","look"],"additionalProperties":false},"hidden":{"type":"boolean"},"locked":{"type":"boolean"}},"required":["id","track","kind","startMs","endMs","time","label"],"additionalProperties":false}},"clipsShown":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clipsTotal":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"trimmed":{"anyOf":[{"type":"string"},{"type":"null"}]},"captions":{"type":"object","properties":{"enabled":{"type":"boolean"},"style":{"type":"string"},"font":{"type":"string"},"position":{"type":"string"},"size":{"type":"number"},"color":{"type":"string"},"highlightColor":{"type":"string"},"background":{"type":"boolean"},"wordsOnScreen":{"type":"number"},"scenesWithWords":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"scenesOff":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["enabled","style","font","position","size","color","highlightColor","background","wordsOnScreen","scenesWithWords","scenesOff"],"additionalProperties":false},"markers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"atMs":{"type":"number"},"at":{"type":"string"},"label":{"type":"string"}},"required":["id","atMs","at","label"],"additionalProperties":false}},"render":{"anyOf":[{"type":"object","properties":{"status":{"description":"idle, queued, rendering, finishing, completed, failed or cancelled.","type":"string"},"progress":{"type":"number"},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"description":"The finished video, once completed.","anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"canCancel":{"type":"boolean"},"stale":{"description":"True when the render stopped reporting for a while; asking again re-checks it with the render service.","type":"boolean"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastVideo":{"description":"The last video the editor finished, and which revision it was made from.","anyOf":[{"type":"object","properties":{"videoUrl":{"type":"string"},"revision":{"anyOf":[{"type":"number"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["videoUrl","revision","finishedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["status","progress","stage","videoUrl","error","canCancel","stale","startedAt","lastVideo"],"additionalProperties":false},{"type":"null"}]},"links":{"type":"object","properties":{"editor":{"type":"string"}},"required":["editor"],"additionalProperties":false}},"required":["product","projectId","variantId","revision","hasSavedEdits","title","aspect","durationMs","duration","videoSpeed","tracks","clips","clipsShown","clipsTotal","trimmed","captions","markers","render","links"],"additionalProperties":false}},"required":["revision","variantId","saved","changes","warnings","undo","timeline"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/automations":{"get":{"operationId":"v3_automations_list","summary":"List your AutoClips V3 automations with their settings, schedule and daily limit.","description":"List your AutoClips V3 automations with their settings, schedule and daily limit.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"v3.automations.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_automations action=list","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automations":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: video.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false}}},"required":["automations"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"automations":[{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Dark Stories","format":"video","status":"active","pauseReason":null,"schedule":{"timezone":"Europe/London","times":["20:00"],"videosPerDay":1},"settings":{"durationSeconds":60,"aspectRatio":"9:16","language":"en","voice":"pNInz6obpgDQGcFmaJgB","imageModel":"fluxSchnell","animated":true,"animationModel":"autoclips1","animateScope":"all","directVideo":true,"faceConsistency":false,"characterIds":[],"show":{"enabled":false},"music":{"mode":"auto","category":"v3-general"}},"topics":{"mode":"category","category":"horror","customTopic":null,"style":null,"goal":"views","goalText":null,"cta":"follow","ctaText":null,"commentWord":null,"commentReward":null,"visitUrl":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":820,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":820,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"v3_automations_create","summary":"Set up an AutoClips V3 automation that makes and posts videos on a schedule, within a daily limit.","description":"Makes an AutoClips V3 automation with every option of the wizard: length, shape, language, narrator, picture and clip models, saved characters, a show (episodes of one series with a fixed cast), captions, sound mix, music, brand, watermark and outro. At each posting time it writes a new video from your topics, and posts it. What you approve is its daily spending limit (spendLimitPerDay; left out, one day of runs at their most): a run that would pass it is skipped until the next day, and a run is settled after it is made, so one step's final cost can run a little over. A value the app would not keep for these settings is refused (400 setting_not_allowed). With publishing, every video is posted automatically: that needs the publish permission, accounts must be yours and platforms on your plan, and the approval names them. The same request again with the same Idempotency-Key hands back the same automation.\n\n**Permissions:** spend, edit.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. V3 automation day stops before a step that would go past the limit, but one step's final cost can run a little over, so the limit is not the most it can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"v3.automations.create","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"v3_automations action=create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The automation's name: unique on your account, at most 100 characters.","type":"string","minLength":1,"maxLength":100},"schedule":{"description":"When it runs. A new automation needs all three; an update changes only what you send.","type":"object","properties":{"timezone":{"description":"The time zone of the posting times (IANA, for example \"America/New_York\").","type":"string","minLength":1,"maxLength":64},"videosPerDay":{"description":"Videos a day, 1 to 3: one per posting time.","type":"integer","minimum":1,"maximum":3},"times":{"description":"The posting times, one per video a day (\"09:00\", 24-hour).","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}}},"additionalProperties":false},"video":{"description":"Every video this automation makes.","type":"object","properties":{"durationSeconds":{"description":"The length in seconds: 60, 65, 75, 90, 100, 120, 180, 300, 600, 900, 1200. Longer lengths need a higher plan.","anyOf":[{"type":"number","const":60},{"type":"number","const":65},{"type":"number","const":75},{"type":"number","const":90},{"type":"number","const":100},{"type":"number","const":120},{"type":"number","const":180},{"type":"number","const":300},{"type":"number","const":600},{"type":"number","const":900},{"type":"number","const":1200}]},"aspectRatio":{"description":"9:16, 16:9 or 1:1.","type":"string","enum":["9:16","16:9","1:1"]},"language":{"description":"The spoken language (autoclips_options product v3, language).","type":"string","minLength":2,"maxLength":12},"speed":{"description":"Video speed, 0.5 to 2.","type":"number","minimum":0.5,"maximum":2},"voice":{"description":"The narrator: a voice id or name from autoclips_voices (the library or your own clones). A new automation needs it.","type":"string","minLength":1,"maxLength":120},"voiceModel":{"description":"The voice model. It is changed for you when it cannot speak the language.","type":"string","enum":["eleven_v4","eleven_v3","eleven_multilingual_v2"]},"imageModel":{"description":"The picture model: webSearch, zImageTurbo, grokImagine, fluxSchnell, seedream5Flash, fluxDev, seedream45, fluxPro, krea2Medium, nanoBanana2.","type":"string","enum":["webSearch","zImageTurbo","grokImagine","fluxSchnell","seedream5Flash","fluxDev","seedream45","fluxPro","krea2Medium","nanoBanana2"]},"faceConsistency":{"description":"Keep faces the same from scene to scene (a picture model that supports it; costs more).","type":"boolean"},"characterIds":{"description":"Up to 4 saved characters who star in every video (v3_characters list). They switch face consistency on.","maxItems":4,"type":"array","items":{"description":"characterId","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"secondsPerImage":{"description":"How long each picture stays, 2 to 6 seconds.","anyOf":[{"type":"number","const":2},{"type":"number","const":3},{"type":"number","const":4},{"type":"number","const":5},{"type":"number","const":6}]},"imageStyle":{"description":"The look: realistic-4k, creepy-toon, claymation, cartoon, fantasy-art, kawaii, cinematic, digital-art, neon-futuristic, comic-book, playground, anime.","type":"string","enum":["realistic-4k","creepy-toon","claymation","cartoon","fantasy-art","kawaii","cinematic","digital-art","neon-futuristic","comic-book","playground","anime"]},"scriptMode":{"description":"The writer: normal or max.","type":"string","enum":["normal","max"]},"sfxMode":{"description":"Sound effects: standard or premium.","type":"string","enum":["standard","premium"]},"animated":{"description":"Scenes move (priced per clip).","type":"boolean"},"animationModel":{"description":"The clip model: autoclips1 (AutoClips 1, 75 credits a clip), autoclips1Upscaled (AutoClips 1 1080p Upscaled, 102 credits a clip), autoclips1Light (AutoClips 1 Lite, 38 credits a clip), autoclips1LightHd (AutoClips 1 Lite Full HD, 113 credits a clip), seedancePro (Seedance 1.5 Pro, 55 credits a clip), seedanceLite (Seedance 1.0 Lite, 100 credits a clip), kling3Video (Kling 3.0, 270 credits a clip), klingVideo (Kling 2.6, 200 credits a clip), grokImagineVideo (Grok Video, 250 credits a clip), omniMax (Pro Max, 400 credits a clip), or autoclipsVideo (AutoClips 1, old name: still taken, saved as autoclips1). omniMax is 9:16 or 16:9 only. autoclips1Light and autoclips1LightHd make no clip from character pictures: not with faceConsistency (or characterIds) and directVideo together.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd","seedancePro","seedanceLite","kling3Video","klingVideo","grokImagineVideo","omniMax","autoclipsVideo"]},"animateScope":{"description":"first: the opening scene moves; all: every scene.","type":"string","enum":["first","all"]},"directVideo":{"description":"Straight from the script: clips with no pictures first (animated, all scenes, on an AutoClips model: autoclips1, autoclips1Upscaled, autoclips1Light or autoclips1LightHd).","type":"boolean"},"cliffhanger":{"description":"End on a cliffhanger.","type":"boolean"},"captions":{"description":"Captions on or off.","type":"boolean"},"motionText":{"description":"The hook card and text cards on the words (9:16 only).","type":"boolean"},"subjectWobble":{"description":"The Creepy Toon wobble.","type":"boolean"},"show":{"type":"object","properties":{"enabled":{"description":"Every video is the next episode of one show, with a fixed cast (characterIds, at least 1) and world.","type":"boolean"},"name":{"type":"string","minLength":1,"maxLength":60},"bible":{"description":"The show in a sentence or two.","type":"string","minLength":20,"maxLength":1200},"episodeStyle":{"description":"continuing: each picks up where the last ended; standalone: a complete story every time.","type":"string","enum":["continuing","standalone"]}},"required":["enabled"],"additionalProperties":false},"customPrompt":{"description":"Extra direction for every video's writer.","type":"string","minLength":1,"maxLength":1000},"captionStyle":{"description":"auto, or: classic, progressive, color-only, background, outline, glow, neon, karaoke, bounce, typewriter, gradient, shadow-pop, underline, scale-up.","type":"string","enum":["auto","classic","progressive","color-only","background","outline","glow","neon","karaoke","bounce","typewriter","gradient","shadow-pop","underline","scale-up"]},"captionFont":{"type":"string","enum":["BebasNeue","Anton","Montserrat","LeagueSpartan"]},"captionFontSize":{"type":"integer","minimum":20,"maximum":120},"captionPosition":{"type":"string","enum":["top","upper-third","center","lower-third","bottom"]},"captionColor":{"description":"#RRGGBB","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"captionHighlightColor":{"description":"#RRGGBB","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"captionBackground":{"description":"A box behind the captions.","type":"boolean"},"captionBackgroundOpacity":{"type":"number","minimum":0,"maximum":1},"narrationVolumeDb":{"type":"number","minimum":-20,"maximum":6},"sfxVolumeDb":{"type":"number","minimum":-30,"maximum":6},"musicVolumeDb":{"type":"number","minimum":-40,"maximum":-4},"music":{"type":"object","properties":{"mode":{"description":"auto: picked for each story; ai: written for each video (costs more); library: a random track of a mood; none.","type":"string","enum":["auto","ai","library","none"]},"category":{"description":"A mood of the music library (a random track of it per video): popular, playful, sneaky, mysterious, epic, chill, upbeat, whimsical, v3-animals, v3-crime, v3-general, v3-history, v3-horror, v3-science, v3-space.","type":"string","enum":["popular","playful","sneaky","mysterious","epic","chill","upbeat","whimsical","v3-animals","v3-crime","v3-general","v3-history","v3-horror","v3-science","v3-space"]}},"required":["mode"],"additionalProperties":false},"brand":{"description":"A brand to work into every video.","type":"object","properties":{"brandId":{"description":"One of your brands (autoclips_automations brands), or null for none.","anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"placement":{"description":"Where it is mentioned: middle or end (default end).","type":"string","enum":["middle","end"]},"mediaMode":{"description":"smart_mix, brand_only or ai_only: which pictures show (default smart_mix).","type":"string","enum":["smart_mix","brand_only","ai_only"]}},"required":["brandId"],"additionalProperties":false}},"additionalProperties":false},"topics":{"description":"Where the ideas come from, and how each video ends.","type":"object","properties":{"mode":{"description":"category: ideas on a topic category; custom: ideas on your own theme.","type":"string","enum":["category","custom"]},"category":{"description":"The topic category: history, science, horror, psychology, tech, nature, money, health, weird, crime, space, food.","type":"string","enum":["history","science","horror","psychology","tech","nature","money","health","weird","crime","space","food"]},"customTopic":{"description":"Your own theme for new ideas.","type":"string","minLength":1,"maxLength":2000},"goal":{"description":"What the videos are for: views, followers, sales, awareness, custom.","type":"string","enum":["views","followers","sales","awareness","custom"]},"goalText":{"description":"Your own goal in words, with goal custom.","type":"string","minLength":1,"maxLength":500},"cta":{"description":"The call to action at the end: follow, comment, visit, subscribe, share, custom.","type":"string","enum":["follow","comment","visit","subscribe","share","custom"]},"ctaText":{"description":"Your own call to action, with cta custom.","type":"string","minLength":1,"maxLength":200},"commentWord":{"description":"The word viewers comment, with cta comment.","type":"string","minLength":1,"maxLength":40},"commentReward":{"description":"What they get for it, with cta comment.","type":"string","minLength":1,"maxLength":120},"visitUrl":{"description":"Where to send viewers, with cta visit: said in the video, never fetched.","type":"string","minLength":1,"maxLength":200}},"additionalProperties":false},"publishing":{"description":"Where each video goes. Switching posting on, changing the posting account or making YouTube videos more public needs the publish permission; only the platforms you send change.","type":"object","properties":{"email":{"description":"Email you when each video is ready.","type":"boolean"},"library":{"description":"Keep each video in My Videos.","type":"boolean"},"tiktok":{"description":"Posting to TikTok.","type":"object","properties":{"enabled":{"description":"Post every video to TikTok.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"youtube":{"description":"Posting to YouTube.","type":"object","properties":{"enabled":{"description":"Post every video to YouTube.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"},"privacy":{"description":"public, unlisted or private (default private; private videos get no comments, so no votes).","type":"string","enum":["public","unlisted","private"]},"categoryId":{"description":"The YouTube category id (2 Autos & Vehicles, 23 Comedy, 27 Education, 24 Entertainment, 1 Film & Animation, 20 Gaming, 26 Howto & Style, 10 Music, 25 News & Politics, 29 Nonprofits & Activism, 22 People & Blogs, 15 Pets & Animals, 28 Science & Technology, 17 Sports, 19 Travel & Events).","type":"string","enum":["1","2","10","15","17","19","20","22","23","24","25","26","27","28","29"]},"useAIMetadata":{"description":"Write the title and description from the video (default true).","type":"boolean"}},"required":["enabled"],"additionalProperties":false},"instagram":{"description":"Posting to Instagram.","type":"object","properties":{"enabled":{"description":"Post every video to Instagram.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"facebook":{"description":"Posting to Facebook.","type":"object","properties":{"enabled":{"description":"Post every video to Facebook.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"twitter":{"description":"Posting to X.","type":"object","properties":{"enabled":{"description":"Post every video to X.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"snapchat":{"description":"Posting to Snapchat.","type":"object","properties":{"enabled":{"description":"Post every video to Snapchat.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false}},"additionalProperties":false},"watermarkType":{"description":"Watermark: Your text or picture on the video. Every plan.\nChoices:\n- none — None: No watermark.\n- text — Text: watermarkText.\n- image — Picture: watermarkMediaId.\nDefault: none.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"Text: The words. Default: No text (leave it out).","type":"string","minLength":1,"maxLength":50},"watermarkTextColor":{"description":"Text colour: #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundColor":{"description":"Box colour: #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundOpacity":{"description":"Box: Box, 0 (none) to 1. From 0 to 1, in steps of 0.01. Default: 0.5.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"watermarkMediaId":{"description":"A picture from autoclips_media, by id. Default: No picture (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"watermarkImageOpacity":{"description":"Picture opacity: 0.3 to 1. From 0.3 to 1, in steps of 0.01. Default: 0.7.","type":"number","minimum":0.3,"maximum":1,"multipleOf":0.01},"watermarkVerticalPosition":{"description":"Height: Percent from the top. From 10 to 90 percent. Default: 85.","type":"integer","minimum":10,"maximum":90},"watermarkHorizontalPosition":{"description":"Across: Percent from the left. From 5 to 95 percent. Default: 85.","type":"integer","minimum":5,"maximum":95},"watermarkScale":{"description":"Size: 1 is normal. From 0.5 to 3, in steps of 0.01. Default: 1.","type":"number","minimum":0.5,"maximum":3,"multipleOf":0.01},"watermarkStartSeconds":{"description":"From: Seconds into the video it appears. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"watermarkEndSeconds":{"description":"Until: Seconds into the video it goes; 0 = to the end. At least 0.5 s after the start. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"outroId":{"description":"Outro: An end card from autoclips_outros, after the last scene. Paid plans (free: plan_required). \"none\" = no outro. Default: No outro (leave it out).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"spendLimitPerDay":{"description":"The most it may spend a day, in credits (1 to 100,000). Left out: one day of runs at their most.","type":"integer","minimum":1,"maximum":100000},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["name","schedule"],"additionalProperties":false},"example":{"name":"Dark Stories","schedule":{"timezone":"Europe/London","videosPerDay":1,"times":["20:00"]},"video":{"durationSeconds":60,"aspectRatio":"9:16","voice":"Adam","imageModel":"fluxSchnell","animated":true,"animationModel":"autoclips1","animateScope":"all","music":{"mode":"auto"}},"topics":{"mode":"category","category":"horror"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: video.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"approvedCreditsPerDay":{"description":"The daily spending limit you approved.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["automation","approvedCreditsPerDay"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Dark Stories","format":"video","status":"active","pauseReason":null,"schedule":{"timezone":"Europe/London","times":["20:00"],"videosPerDay":1},"settings":{"durationSeconds":60,"aspectRatio":"9:16","language":"en","voice":"pNInz6obpgDQGcFmaJgB","imageModel":"fluxSchnell","animated":true,"animationModel":"autoclips1","animateScope":"all","directVideo":true,"faceConsistency":false,"characterIds":[],"show":{"enabled":false},"music":{"mode":"auto","category":"v3-general"}},"topics":{"mode":"category","category":"horror","customTopic":null,"style":null,"goal":"views","goalText":null,"cta":"follow","ctaText":null,"commentWord":null,"commentReward":null,"visitUrl":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":820,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":820,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},"approvedCreditsPerDay":820}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/automations/{automationId}":{"get":{"operationId":"v3_automations_get","summary":"Read one automation: its settings, schedule, daily limit and last 10 runs.","description":"Read one automation: its settings, schedule, daily limit and last 10 runs.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"v3.automations.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_automations action=get","parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: video.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"recentRuns":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"testRun":{"type":"boolean"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsUsed":{"type":"number"},"posts":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"published":{"type":"boolean"},"link":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["published","link"],"additionalProperties":false}},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","testRun","topic","projectId","videoUrl","creditsUsed","posts","error","startedAt","completedAt"],"additionalProperties":false}}},"required":["automation","recentRuns"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Dark Stories","format":"video","status":"active","pauseReason":null,"schedule":{"timezone":"Europe/London","times":["20:00"],"videosPerDay":1},"settings":{"durationSeconds":60,"aspectRatio":"9:16","language":"en","voice":"pNInz6obpgDQGcFmaJgB","imageModel":"fluxSchnell","animated":true,"animationModel":"autoclips1","animateScope":"all","directVideo":true,"faceConsistency":false,"characterIds":[],"show":{"enabled":false},"music":{"mode":"auto","category":"v3-general"}},"topics":{"mode":"category","category":"horror","customTopic":null,"style":null,"goal":"views","goalText":null,"cta":"follow","ctaText":null,"commentWord":null,"commentReward":null,"visitUrl":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":820,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":820,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},"recentRuns":[{"id":"3e9a7c10-52bd-4f68-a1c7-8d20f4b6e913","status":"completed","testRun":false,"topic":"Why octopuses have three hearts","projectId":"c4a2d3e5-6f70-4b8c-9dae-1f2a3b4c5d6e","videoUrl":"https://media.autoclips.app/videos/example.mp4","creditsUsed":820,"posts":{},"error":null,"startedAt":"2026-11-01T09:00:00.000Z","completedAt":"2026-11-01T09:12:00.000Z"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"v3_automations_update","summary":"Change an automation's name, schedule, settings, topics or posting.","description":"Changes the parts you send; everything else stays. Changes apply from the next run. A change of what the videos are about writes new topics (it counts toward the free-AI daily limit). A change that raises what a day can spend above the daily limit, or any raise when it has none, is refused: set the limit first with set_spend_limit (409 spend_limit_needed). Switching posting on, adding a platform, changing the posting account or making YouTube more public needs the publish permission, and AI apps ask first.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.automations.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_automations action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The automation's name: unique on your account, at most 100 characters.","type":"string","minLength":1,"maxLength":100},"schedule":{"description":"When it runs. A new automation needs all three; an update changes only what you send.","type":"object","properties":{"timezone":{"description":"The time zone of the posting times (IANA, for example \"America/New_York\").","type":"string","minLength":1,"maxLength":64},"videosPerDay":{"description":"Videos a day, 1 to 3: one per posting time.","type":"integer","minimum":1,"maximum":3},"times":{"description":"The posting times, one per video a day (\"09:00\", 24-hour).","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}}},"additionalProperties":false},"video":{"description":"Every video this automation makes.","type":"object","properties":{"durationSeconds":{"description":"The length in seconds: 60, 65, 75, 90, 100, 120, 180, 300, 600, 900, 1200. Longer lengths need a higher plan.","anyOf":[{"type":"number","const":60},{"type":"number","const":65},{"type":"number","const":75},{"type":"number","const":90},{"type":"number","const":100},{"type":"number","const":120},{"type":"number","const":180},{"type":"number","const":300},{"type":"number","const":600},{"type":"number","const":900},{"type":"number","const":1200}]},"aspectRatio":{"description":"9:16, 16:9 or 1:1.","type":"string","enum":["9:16","16:9","1:1"]},"language":{"description":"The spoken language (autoclips_options product v3, language).","type":"string","minLength":2,"maxLength":12},"speed":{"description":"Video speed, 0.5 to 2.","type":"number","minimum":0.5,"maximum":2},"voice":{"description":"The narrator: a voice id or name from autoclips_voices (the library or your own clones). A new automation needs it.","type":"string","minLength":1,"maxLength":120},"voiceModel":{"description":"The voice model. It is changed for you when it cannot speak the language.","type":"string","enum":["eleven_v4","eleven_v3","eleven_multilingual_v2"]},"imageModel":{"description":"The picture model: webSearch, zImageTurbo, grokImagine, fluxSchnell, seedream5Flash, fluxDev, seedream45, fluxPro, krea2Medium, nanoBanana2.","type":"string","enum":["webSearch","zImageTurbo","grokImagine","fluxSchnell","seedream5Flash","fluxDev","seedream45","fluxPro","krea2Medium","nanoBanana2"]},"faceConsistency":{"description":"Keep faces the same from scene to scene (a picture model that supports it; costs more).","type":"boolean"},"characterIds":{"description":"Up to 4 saved characters who star in every video (v3_characters list). They switch face consistency on.","maxItems":4,"type":"array","items":{"description":"characterId","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"secondsPerImage":{"description":"How long each picture stays, 2 to 6 seconds.","anyOf":[{"type":"number","const":2},{"type":"number","const":3},{"type":"number","const":4},{"type":"number","const":5},{"type":"number","const":6}]},"imageStyle":{"description":"The look: realistic-4k, creepy-toon, claymation, cartoon, fantasy-art, kawaii, cinematic, digital-art, neon-futuristic, comic-book, playground, anime.","type":"string","enum":["realistic-4k","creepy-toon","claymation","cartoon","fantasy-art","kawaii","cinematic","digital-art","neon-futuristic","comic-book","playground","anime"]},"scriptMode":{"description":"The writer: normal or max.","type":"string","enum":["normal","max"]},"sfxMode":{"description":"Sound effects: standard or premium.","type":"string","enum":["standard","premium"]},"animated":{"description":"Scenes move (priced per clip).","type":"boolean"},"animationModel":{"description":"The clip model: autoclips1 (AutoClips 1, 75 credits a clip), autoclips1Upscaled (AutoClips 1 1080p Upscaled, 102 credits a clip), autoclips1Light (AutoClips 1 Lite, 38 credits a clip), autoclips1LightHd (AutoClips 1 Lite Full HD, 113 credits a clip), seedancePro (Seedance 1.5 Pro, 55 credits a clip), seedanceLite (Seedance 1.0 Lite, 100 credits a clip), kling3Video (Kling 3.0, 270 credits a clip), klingVideo (Kling 2.6, 200 credits a clip), grokImagineVideo (Grok Video, 250 credits a clip), omniMax (Pro Max, 400 credits a clip), or autoclipsVideo (AutoClips 1, old name: still taken, saved as autoclips1). omniMax is 9:16 or 16:9 only. autoclips1Light and autoclips1LightHd make no clip from character pictures: not with faceConsistency (or characterIds) and directVideo together.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd","seedancePro","seedanceLite","kling3Video","klingVideo","grokImagineVideo","omniMax","autoclipsVideo"]},"animateScope":{"description":"first: the opening scene moves; all: every scene.","type":"string","enum":["first","all"]},"directVideo":{"description":"Straight from the script: clips with no pictures first (animated, all scenes, on an AutoClips model: autoclips1, autoclips1Upscaled, autoclips1Light or autoclips1LightHd).","type":"boolean"},"cliffhanger":{"description":"End on a cliffhanger.","type":"boolean"},"captions":{"description":"Captions on or off.","type":"boolean"},"motionText":{"description":"The hook card and text cards on the words (9:16 only).","type":"boolean"},"subjectWobble":{"description":"The Creepy Toon wobble.","type":"boolean"},"show":{"type":"object","properties":{"enabled":{"description":"Every video is the next episode of one show, with a fixed cast (characterIds, at least 1) and world.","type":"boolean"},"name":{"type":"string","minLength":1,"maxLength":60},"bible":{"description":"The show in a sentence or two.","type":"string","minLength":20,"maxLength":1200},"episodeStyle":{"description":"continuing: each picks up where the last ended; standalone: a complete story every time.","type":"string","enum":["continuing","standalone"]}},"required":["enabled"],"additionalProperties":false},"customPrompt":{"description":"Extra direction for every video's writer.","type":"string","minLength":1,"maxLength":1000},"captionStyle":{"description":"auto, or: classic, progressive, color-only, background, outline, glow, neon, karaoke, bounce, typewriter, gradient, shadow-pop, underline, scale-up.","type":"string","enum":["auto","classic","progressive","color-only","background","outline","glow","neon","karaoke","bounce","typewriter","gradient","shadow-pop","underline","scale-up"]},"captionFont":{"type":"string","enum":["BebasNeue","Anton","Montserrat","LeagueSpartan"]},"captionFontSize":{"type":"integer","minimum":20,"maximum":120},"captionPosition":{"type":"string","enum":["top","upper-third","center","lower-third","bottom"]},"captionColor":{"description":"#RRGGBB","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"captionHighlightColor":{"description":"#RRGGBB","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"captionBackground":{"description":"A box behind the captions.","type":"boolean"},"captionBackgroundOpacity":{"type":"number","minimum":0,"maximum":1},"narrationVolumeDb":{"type":"number","minimum":-20,"maximum":6},"sfxVolumeDb":{"type":"number","minimum":-30,"maximum":6},"musicVolumeDb":{"type":"number","minimum":-40,"maximum":-4},"music":{"type":"object","properties":{"mode":{"description":"auto: picked for each story; ai: written for each video (costs more); library: a random track of a mood; none.","type":"string","enum":["auto","ai","library","none"]},"category":{"description":"A mood of the music library (a random track of it per video): popular, playful, sneaky, mysterious, epic, chill, upbeat, whimsical, v3-animals, v3-crime, v3-general, v3-history, v3-horror, v3-science, v3-space.","type":"string","enum":["popular","playful","sneaky","mysterious","epic","chill","upbeat","whimsical","v3-animals","v3-crime","v3-general","v3-history","v3-horror","v3-science","v3-space"]}},"required":["mode"],"additionalProperties":false},"brand":{"description":"A brand to work into every video.","type":"object","properties":{"brandId":{"description":"One of your brands (autoclips_automations brands), or null for none.","anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"placement":{"description":"Where it is mentioned: middle or end (default end).","type":"string","enum":["middle","end"]},"mediaMode":{"description":"smart_mix, brand_only or ai_only: which pictures show (default smart_mix).","type":"string","enum":["smart_mix","brand_only","ai_only"]}},"required":["brandId"],"additionalProperties":false}},"additionalProperties":false},"topics":{"description":"Where the ideas come from, and how each video ends.","type":"object","properties":{"mode":{"description":"category: ideas on a topic category; custom: ideas on your own theme.","type":"string","enum":["category","custom"]},"category":{"description":"The topic category: history, science, horror, psychology, tech, nature, money, health, weird, crime, space, food.","type":"string","enum":["history","science","horror","psychology","tech","nature","money","health","weird","crime","space","food"]},"customTopic":{"description":"Your own theme for new ideas.","type":"string","minLength":1,"maxLength":2000},"goal":{"description":"What the videos are for: views, followers, sales, awareness, custom.","type":"string","enum":["views","followers","sales","awareness","custom"]},"goalText":{"description":"Your own goal in words, with goal custom.","type":"string","minLength":1,"maxLength":500},"cta":{"description":"The call to action at the end: follow, comment, visit, subscribe, share, custom.","type":"string","enum":["follow","comment","visit","subscribe","share","custom"]},"ctaText":{"description":"Your own call to action, with cta custom.","type":"string","minLength":1,"maxLength":200},"commentWord":{"description":"The word viewers comment, with cta comment.","type":"string","minLength":1,"maxLength":40},"commentReward":{"description":"What they get for it, with cta comment.","type":"string","minLength":1,"maxLength":120},"visitUrl":{"description":"Where to send viewers, with cta visit: said in the video, never fetched.","type":"string","minLength":1,"maxLength":200}},"additionalProperties":false},"publishing":{"description":"Where each video goes. Switching posting on, changing the posting account or making YouTube videos more public needs the publish permission; only the platforms you send change.","type":"object","properties":{"email":{"description":"Email you when each video is ready.","type":"boolean"},"library":{"description":"Keep each video in My Videos.","type":"boolean"},"tiktok":{"description":"Posting to TikTok.","type":"object","properties":{"enabled":{"description":"Post every video to TikTok.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"youtube":{"description":"Posting to YouTube.","type":"object","properties":{"enabled":{"description":"Post every video to YouTube.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"},"privacy":{"description":"public, unlisted or private (default private; private videos get no comments, so no votes).","type":"string","enum":["public","unlisted","private"]},"categoryId":{"description":"The YouTube category id (2 Autos & Vehicles, 23 Comedy, 27 Education, 24 Entertainment, 1 Film & Animation, 20 Gaming, 26 Howto & Style, 10 Music, 25 News & Politics, 29 Nonprofits & Activism, 22 People & Blogs, 15 Pets & Animals, 28 Science & Technology, 17 Sports, 19 Travel & Events).","type":"string","enum":["1","2","10","15","17","19","20","22","23","24","25","26","27","28","29"]},"useAIMetadata":{"description":"Write the title and description from the video (default true).","type":"boolean"}},"required":["enabled"],"additionalProperties":false},"instagram":{"description":"Posting to Instagram.","type":"object","properties":{"enabled":{"description":"Post every video to Instagram.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"facebook":{"description":"Posting to Facebook.","type":"object","properties":{"enabled":{"description":"Post every video to Facebook.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"twitter":{"description":"Posting to X.","type":"object","properties":{"enabled":{"description":"Post every video to X.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false},"snapchat":{"description":"Posting to Snapchat.","type":"object","properties":{"enabled":{"description":"Post every video to Snapchat.","type":"boolean"},"accountId":{"description":"The connected account to post with (its id from autoclips_publish accounts). Left out: the account of the automation's social profile.","type":"string","pattern":"^[a-f0-9]{24}$"}},"required":["enabled"],"additionalProperties":false}},"additionalProperties":false},"watermarkType":{"description":"Watermark: Your text or picture on the video. Every plan.\nChoices:\n- none — None: No watermark.\n- text — Text: watermarkText.\n- image — Picture: watermarkMediaId.\nDefault: none.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"Text: The words. Default: No text (leave it out).","type":"string","minLength":1,"maxLength":50},"watermarkTextColor":{"description":"Text colour: #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundColor":{"description":"Box colour: #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundOpacity":{"description":"Box: Box, 0 (none) to 1. From 0 to 1, in steps of 0.01. Default: 0.5.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"watermarkMediaId":{"description":"A picture from autoclips_media, by id. Default: No picture (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"watermarkImageOpacity":{"description":"Picture opacity: 0.3 to 1. From 0.3 to 1, in steps of 0.01. Default: 0.7.","type":"number","minimum":0.3,"maximum":1,"multipleOf":0.01},"watermarkVerticalPosition":{"description":"Height: Percent from the top. From 10 to 90 percent. Default: 85.","type":"integer","minimum":10,"maximum":90},"watermarkHorizontalPosition":{"description":"Across: Percent from the left. From 5 to 95 percent. Default: 85.","type":"integer","minimum":5,"maximum":95},"watermarkScale":{"description":"Size: 1 is normal. From 0.5 to 3, in steps of 0.01. Default: 1.","type":"number","minimum":0.5,"maximum":3,"multipleOf":0.01},"watermarkStartSeconds":{"description":"From: Seconds into the video it appears. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"watermarkEndSeconds":{"description":"Until: Seconds into the video it goes; 0 = to the end. At least 0.5 s after the start. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"outroId":{"description":"Outro: An end card from autoclips_outros, after the last scene. Paid plans (free: plan_required). \"none\" = no outro. Default: No outro (leave it out).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"additionalProperties":false},"example":{"schedule":{"times":["18:00"]}}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: video.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"ideasRewritten":{"description":"True when the change writes new topics.","type":"boolean"}},"required":["automation","ideasRewritten"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Dark Stories","format":"video","status":"active","pauseReason":null,"schedule":{"timezone":"Europe/London","times":["18:00"],"videosPerDay":1},"settings":{"durationSeconds":60,"aspectRatio":"9:16","language":"en","voice":"pNInz6obpgDQGcFmaJgB","imageModel":"fluxSchnell","animated":true,"animationModel":"autoclips1","animateScope":"all","directVideo":true,"faceConsistency":false,"characterIds":[],"show":{"enabled":false},"music":{"mode":"auto","category":"v3-general"}},"topics":{"mode":"category","category":"horror","customTopic":null,"style":null,"goal":"views","goalText":null,"cta":"follow","ctaText":null,"commentWord":null,"commentReward":null,"visitUrl":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":820,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":820,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},"ideasRewritten":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"v3_automations_delete","summary":"Delete an automation and its run history. Its videos stay in My Videos.","description":"Deletes the automation and its run history. Refused while a run is being made (409 run_active: wait, or cancel_run), so no run is left without its refund.\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"v3.automations.delete","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_automations action=delete","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"deleted":true,"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/automations/{automationId}/pause":{"post":{"operationId":"v3_automations_pause","summary":"Pause an automation; it makes nothing until it is resumed.","description":"Pause an automation; it makes nothing until it is resumed.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.automations.pause","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_automations action=pause","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: video.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"changed":{"description":"False when it was already paused.","type":"boolean"}},"required":["automation","changed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Dark Stories","format":"video","status":"paused","pauseReason":null,"schedule":{"timezone":"Europe/London","times":["20:00"],"videosPerDay":1},"settings":{"durationSeconds":60,"aspectRatio":"9:16","language":"en","voice":"pNInz6obpgDQGcFmaJgB","imageModel":"fluxSchnell","animated":true,"animationModel":"autoclips1","animateScope":"all","directVideo":true,"faceConsistency":false,"characterIds":[],"show":{"enabled":false},"music":{"mode":"auto","category":"v3-general"}},"topics":{"mode":"category","category":"horror","customTopic":null,"style":null,"goal":"views","goalText":null,"cta":"follow","ctaText":null,"commentWord":null,"commentReward":null,"visitUrl":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":820,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":820,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},"changed":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/automations/{automationId}/resume":{"post":{"operationId":"v3_automations_resume","summary":"Resume a paused automation at its next posting time.","description":"Runs again from its next posting time. It needs a daily spending limit (409 spend_limit_needed: set one with set_spend_limit). Resuming an automation that posts needs the publish permission, and AI apps ask first.\n\n**Permissions:** edit, spend.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"v3.automations.resume","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_automations action=resume","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: video.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false},"changed":{"description":"False when it was already active.","type":"boolean"}},"required":["automation","changed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Dark Stories","format":"video","status":"active","pauseReason":null,"schedule":{"timezone":"Europe/London","times":["20:00"],"videosPerDay":1},"settings":{"durationSeconds":60,"aspectRatio":"9:16","language":"en","voice":"pNInz6obpgDQGcFmaJgB","imageModel":"fluxSchnell","animated":true,"animationModel":"autoclips1","animateScope":"all","directVideo":true,"faceConsistency":false,"characterIds":[],"show":{"enabled":false},"music":{"mode":"auto","category":"v3-general"}},"topics":{"mode":"category","category":"horror","customTopic":null,"style":null,"goal":"views","goalText":null,"cta":"follow","ctaText":null,"commentWord":null,"commentReward":null,"visitUrl":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":820,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":820,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},"changed":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/automations/{automationId}/runs":{"post":{"operationId":"v3_automations_run_now","summary":"Make the next video of an automation now, and post it as the schedule would. Answers with a job.","description":"Makes the automation's next video right now (the app's Test button) and posts it where the automation posts. The price is the run at its most; what it does not use is given back when it is settled, and a failed run is refunded. One run at a time (409 run_in_progress), at most one every 5 minutes (429). If every posting account needs reconnecting, nothing is made or charged (409 social_token_expired). An automation that posts needs the publish permission. It answers with a job (status 202): follow it with autoclips_jobs get.\n\n**Permissions:** spend, edit.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["spend","edit"]}],"x-autoclips-operation":"v3.automations.run_now","x-autoclips-scopes":["spend","edit"],"x-autoclips-cost":"paid","x-autoclips-mcp":"v3_automations action=run_now","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"run":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}},"required":["id","status"],"additionalProperties":false},"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false}},"required":["run","job"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"run":{"id":"3e9a7c10-52bd-4f68-a1c7-8d20f4b6e913","status":"generating"},"job":{"id":"job_019a1b2c3d4e5f60718293e7","product":"v3","kind":"v3.automation_run","resource":{"type":"automation_run","id":"3e9a7c10-52bd-4f68-a1c7-8d20f4b6e913"},"status":"queued","step":"Starting the run","progress":null,"result":null,"error":null,"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","finishedAt":null,"poll_after_seconds":15}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"v3_automations_runs","summary":"List an automation's recent runs: what each made, where it posted and what it used.","description":"List an automation's recent runs: what each made, where it posted and what it used.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"v3.automations.runs","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_automations action=runs","parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"limit","in":"query","required":false,"schema":{"description":"How many runs (1-50, default 10).","type":"integer","minimum":1,"maximum":50},"description":"How many runs (1-50, default 10).","example":5},{"name":"status","in":"query","required":false,"schema":{"description":"Only runs with this status: pending, generating, completed, failed or cancelled.","type":"string","enum":["pending","generating","completed","failed","cancelled"]},"description":"Only runs with this status: pending, generating, completed, failed or cancelled."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runs":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"testRun":{"type":"boolean"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsUsed":{"type":"number"},"posts":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"published":{"type":"boolean"},"link":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["published","link"],"additionalProperties":false}},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","testRun","topic","projectId","videoUrl","creditsUsed","posts","error","startedAt","completedAt"],"additionalProperties":false}}},"required":["runs"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"runs":[{"id":"3e9a7c10-52bd-4f68-a1c7-8d20f4b6e913","status":"completed","testRun":false,"topic":"Why octopuses have three hearts","projectId":"c4a2d3e5-6f70-4b8c-9dae-1f2a3b4c5d6e","videoUrl":"https://media.autoclips.app/videos/example.mp4","creditsUsed":820,"posts":{},"error":null,"startedAt":"2026-11-01T09:00:00.000Z","completedAt":"2026-11-01T09:12:00.000Z"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/automations/{automationId}/runs/cancel":{"post":{"operationId":"v3_automations_cancel_run","summary":"Stop the run an automation is making now. Nothing is posted.","description":"Stops the run the automation is making now (or the one runId names). What it has not used yet is given back. 404 when no run is being made.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.automations.cancel_run","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_automations action=cancel_run","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"description":"The run to stop (from runs). Left out: the one being made now.","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runId":{"anyOf":[{"type":"string"},{"type":"null"}]},"cancelled":{"type":"boolean"},"creditsRefunded":{"description":"What came back.","type":"number"}},"required":["runId","cancelled","creditsRefunded"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"runId":"3e9a7c10-52bd-4f68-a1c7-8d20f4b6e913","cancelled":true,"creditsRefunded":820}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/automations/{automationId}/spend-limit":{"put":{"operationId":"v3_automations_set_spend_limit","summary":"Set how much an automation may spend a day.","description":"Sets the daily spending limit: a run that would pass it is skipped until the next day (a run is settled after it is made, so one step's final cost can run a little over). It must allow at least one run (400 spend_limit_too_low). It resumes nothing.\n\n**Permissions:** spend.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. V3 automation day stops before a step that would go past the limit, but one step's final cost can run a little over, so the limit is not the most it can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["spend"]}],"x-autoclips-operation":"v3.automations.set_spend_limit","x-autoclips-scopes":["spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"v3_automations action=set_spend_limit","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"spendLimitPerDay":{"description":"The most it may spend a day, in credits (1 to 100,000). Left out: one day of runs at their most.","type":"integer","minimum":1,"maximum":100000},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"required":["spendLimitPerDay"],"additionalProperties":false},"example":{"spendLimitPerDay":1640}}}},"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"description":"The automation's id (from list).","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The automation's id (from list).","example":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"description":"Which settings it takes: video.","type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pauseReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"times":{"type":"array","items":{"type":"string"}},"videosPerDay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["timezone","times","videosPerDay"],"additionalProperties":false},"settings":{"description":"Every setting in the words create and update take, defaults filled in.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"topics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publishing":{"type":"object","properties":{"email":{"type":"boolean"},"library":{"type":"boolean"},"tiktok":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"youtube":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"instagram":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"facebook":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"twitter":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}},"snapchat":{"type":"object","properties":{"enabled":{"type":"boolean"},"accountId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","accountId"],"additionalProperties":{}}},"required":["email","library","tiktok","youtube","instagram","facebook","twitter","snapchat"],"additionalProperties":false},"spendLimit":{"anyOf":[{"type":"object","properties":{"creditsPerDay":{"type":"number"},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["creditsPerDay","approvedAt"],"additionalProperties":false},{"type":"null"}]},"estimatedCreditsPerRun":{"anyOf":[{"type":"number"},{"type":"null"}]},"stats":{"type":"object","properties":{"videosGenerated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalCreditsUsed":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["videosGenerated","totalCreditsUsed","lastRunAt","nextRunAt","consecutiveFailures"],"additionalProperties":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"appUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","format","status","pauseReason","schedule","settings","publishing","spendLimit","estimatedCreditsPerRun","stats","createdAt","updatedAt","appUrl"],"additionalProperties":false}},"required":["automation"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"automation":{"id":"6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77","name":"Dark Stories","format":"video","status":"active","pauseReason":null,"schedule":{"timezone":"Europe/London","times":["20:00"],"videosPerDay":1},"settings":{"durationSeconds":60,"aspectRatio":"9:16","language":"en","voice":"pNInz6obpgDQGcFmaJgB","imageModel":"fluxSchnell","animated":true,"animationModel":"autoclips1","animateScope":"all","directVideo":true,"faceConsistency":false,"characterIds":[],"show":{"enabled":false},"music":{"mode":"auto","category":"v3-general"}},"topics":{"mode":"category","category":"horror","customTopic":null,"style":null,"goal":"views","goalText":null,"cta":"follow","ctaText":null,"commentWord":null,"commentReward":null,"visitUrl":null},"publishing":{"email":true,"library":true,"tiktok":{"enabled":false,"accountId":null},"youtube":{"enabled":false,"accountId":null},"instagram":{"enabled":false,"accountId":null},"facebook":{"enabled":false,"accountId":null},"twitter":{"enabled":false,"accountId":null},"snapchat":{"enabled":false,"accountId":null}},"spendLimit":{"creditsPerDay":1640,"approvedAt":"2026-11-01T09:00:00.000Z"},"estimatedCreditsPerRun":820,"stats":{"videosGenerated":0,"totalCreditsUsed":0,"lastRunAt":null,"nextRunAt":"2026-11-01T22:00:00.000Z","consecutiveFailures":0},"createdAt":"2026-11-01T09:00:00.000Z","updatedAt":"2026-11-01T09:00:00.000Z","appUrl":"https://app.autoclips.app/automations/6b0f3c52-7d41-4e9a-8c15-2f6a9d3b1e77"}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/characters":{"get":{"operationId":"v3_characters_list","summary":"List your saved V3 characters and the AutoClips starter characters.","description":"Your characters come newest first (up to 500), then the starter characters everyone can use. presets=clay lists the Claymation starter set instead of the default one.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"v3.characters.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_characters action=list","parameters":[{"name":"presets","in":"query","required":false,"schema":{"description":"Which starter characters to include: default (V3 and Time Travel) or clay (Claymation). Your own characters are always listed.","type":"string","enum":["default","clay"]},"description":"Which starter characters to include: default (V3 and Time Travel) or clay (Claymation). Your own characters are always listed.","example":"clay"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"characters":{"description":"Your own characters.","type":"array","items":{"type":"object","properties":{"id":{"description":"The character id. Use it to put the character in a V3 video, or with get, update, delete, regenerate_sheet and build_sheet.","type":"string"},"name":{"type":"string"},"description":{"description":"How the character looks, in words. The AI uses it with the sheet.","type":"string"},"sheetUrl":{"description":"The reference sheet picture that keeps the face the same in every scene.","anyOf":[{"type":"string"},{"type":"null"}]},"sheets":{"description":"Every sheet this character has had, oldest first (the last 20). Empty for a character whose sheet has not changed since AutoClips began keeping them. Switching back to one with update (sheetUrl) is free.","type":"array","items":{"type":"object","properties":{"url":{"description":"The sheet picture. Send it as sheetUrl to update to make it the character's sheet again.","type":"string"},"label":{"description":"What made it: the model's name, or \"From your photos\" for a sheet built from photos.","type":"string"},"model":{"description":"The model picked for it (grokImagine, seedream45, krea2Medium, seedream5Pro), or grounded for a sheet built from photos; null when not recorded.","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"generated (drawn from the description) or grounded (built from photos); older sheets can carry the character's source.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"current":{"description":"True for the sheet the character uses now.","type":"boolean"}},"required":["url","label","model","kind","createdAt","current"],"additionalProperties":false}},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"generated (drawn from a description), uploaded (from photos), from-video (saved from a project) or preset (an AutoClips starter character).","type":"string"},"isPreset":{"description":"True for AutoClips starter characters. Everyone can use them; nobody can change them.","type":"boolean"},"style":{"description":"The V3 style it was drawn in, when it was one of the V3 styles.","anyOf":[{"type":"string"},{"type":"null"}]},"photos":{"description":"The photos it was made from (characters made from photos only).","type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"view":{"anyOf":[{"type":"string","enum":["front","three-quarter","side","back","smiling","other"]},{"type":"null"}]}},"required":["url","view"],"additionalProperties":false}},"hasPhotoSheet":{"description":"True once build_sheet has turned the photos into a turnaround sheet.","type":"boolean"},"voice":{"description":"The character's own voice, used when the character speaks in character clips.","anyOf":[{"type":"object","properties":{"voiceId":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string","enum":["library","cloned"]}},"required":["voiceId","name","source"],"additionalProperties":false},{"type":"null"}]},"usageCount":{"description":"How many videos used it.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"canChange":{"description":"You can rename it, describe it, give it a voice, switch back to an earlier sheet or delete it.","type":"boolean"},"canRegenerateSheet":{"description":"regenerate_sheet works for it (characters drawn from a description).","type":"boolean"},"canBuildSheet":{"description":"build_sheet works for it (characters made from photos).","type":"boolean"}},"required":["id","name","description","sheetUrl","sheets","thumbnailUrl","source","isPreset","style","photos","hasPhotoSheet","voice","usageCount","createdAt","updatedAt","canChange","canRegenerateSheet","canBuildSheet"],"additionalProperties":false}},"presets":{"description":"AutoClips starter characters.","type":"array","items":{"type":"object","properties":{"id":{"description":"The character id. Use it to put the character in a V3 video, or with get, update, delete, regenerate_sheet and build_sheet.","type":"string"},"name":{"type":"string"},"description":{"description":"How the character looks, in words. The AI uses it with the sheet.","type":"string"},"sheetUrl":{"description":"The reference sheet picture that keeps the face the same in every scene.","anyOf":[{"type":"string"},{"type":"null"}]},"sheets":{"description":"Every sheet this character has had, oldest first (the last 20). Empty for a character whose sheet has not changed since AutoClips began keeping them. Switching back to one with update (sheetUrl) is free.","type":"array","items":{"type":"object","properties":{"url":{"description":"The sheet picture. Send it as sheetUrl to update to make it the character's sheet again.","type":"string"},"label":{"description":"What made it: the model's name, or \"From your photos\" for a sheet built from photos.","type":"string"},"model":{"description":"The model picked for it (grokImagine, seedream45, krea2Medium, seedream5Pro), or grounded for a sheet built from photos; null when not recorded.","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"generated (drawn from the description) or grounded (built from photos); older sheets can carry the character's source.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"current":{"description":"True for the sheet the character uses now.","type":"boolean"}},"required":["url","label","model","kind","createdAt","current"],"additionalProperties":false}},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"generated (drawn from a description), uploaded (from photos), from-video (saved from a project) or preset (an AutoClips starter character).","type":"string"},"isPreset":{"description":"True for AutoClips starter characters. Everyone can use them; nobody can change them.","type":"boolean"},"style":{"description":"The V3 style it was drawn in, when it was one of the V3 styles.","anyOf":[{"type":"string"},{"type":"null"}]},"photos":{"description":"The photos it was made from (characters made from photos only).","type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"view":{"anyOf":[{"type":"string","enum":["front","three-quarter","side","back","smiling","other"]},{"type":"null"}]}},"required":["url","view"],"additionalProperties":false}},"hasPhotoSheet":{"description":"True once build_sheet has turned the photos into a turnaround sheet.","type":"boolean"},"voice":{"description":"The character's own voice, used when the character speaks in character clips.","anyOf":[{"type":"object","properties":{"voiceId":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string","enum":["library","cloned"]}},"required":["voiceId","name","source"],"additionalProperties":false},{"type":"null"}]},"usageCount":{"description":"How many videos used it.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"canChange":{"description":"You can rename it, describe it, give it a voice, switch back to an earlier sheet or delete it.","type":"boolean"},"canRegenerateSheet":{"description":"regenerate_sheet works for it (characters drawn from a description).","type":"boolean"},"canBuildSheet":{"description":"build_sheet works for it (characters made from photos).","type":"boolean"}},"required":["id","name","description","sheetUrl","sheets","thumbnailUrl","source","isPreset","style","photos","hasPhotoSheet","voice","usageCount","createdAt","updatedAt","canChange","canRegenerateSheet","canBuildSheet"],"additionalProperties":false}}},"required":["characters","presets"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"characters":[{"id":"0f8c2a4e-6b1d-4c3e-9a7f-2d5e8b1c4a90","name":"Maya","description":"A 30-year-old baker with curly red hair tied up, freckles, a flour-dusted green apron over a white shirt.","sheetUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1759050000000.jpg","sheets":[{"url":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1758358800000.jpg","label":"Fast and sharp (Grok Imagine)","model":"grokImagine","kind":"generated","createdAt":"2026-09-20T09:00:00.000Z","current":false},{"url":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1759050000000.jpg","label":"Most artistic (Krea 2)","model":"krea2Medium","kind":"generated","createdAt":"2026-09-25T14:30:00.000Z","current":true}],"thumbnailUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1759050000000.jpg","source":"generated","isPreset":false,"style":null,"photos":[],"hasPhotoSheet":false,"voice":null,"usageCount":2,"createdAt":"2026-09-20T09:00:00.000Z","updatedAt":"2026-09-25T14:30:00.000Z","canChange":true,"canRegenerateSheet":true,"canBuildSheet":false},{"id":"7b3d9e21-4f5a-4c8b-a1d2-3e4f5a6b7c8d","name":"Grandpa Joe","description":"An elderly man with a white beard and round glasses, in a brown cardigan.","sheetUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-grandpa-joe-5e6f7a8b/source-0-1759050000000.jpg","sheets":[],"thumbnailUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-grandpa-joe-5e6f7a8b/source-0-1759050000000.jpg","source":"uploaded","isPreset":false,"style":null,"photos":[{"url":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-grandpa-joe-5e6f7a8b/source-0-1759050000000.jpg","view":"front"},{"url":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-grandpa-joe-5e6f7a8b/source-1-1759050000000.jpg","view":"side"}],"hasPhotoSheet":false,"voice":null,"usageCount":0,"createdAt":"2026-09-20T09:00:00.000Z","updatedAt":"2026-09-25T14:30:00.000Z","canChange":true,"canRegenerateSheet":false,"canBuildSheet":true}],"presets":[{"id":"preset-detective-sam","name":"Detective Sam","description":"A tired city detective in a long beige trench coat and a grey fedora.","sheetUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1759050000000.jpg","sheets":[],"thumbnailUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1759050000000.jpg","source":"preset","isPreset":true,"style":null,"photos":[],"hasPhotoSheet":false,"voice":null,"usageCount":0,"createdAt":"2026-09-20T09:00:00.000Z","updatedAt":"2026-09-25T14:30:00.000Z","canChange":false,"canRegenerateSheet":false,"canBuildSheet":false}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"v3_characters_create","summary":"Make a character from 1 to 5 photos in your media library. Free.","description":"Pick 1 to 5 JPG, PNG or WebP pictures (up to 8 MB each) from your media library by media id; bring new ones in with autoclips_media first. Tag what each shows (front, three-quarter, side, back, smiling, other) or leave it out and AI tags it. Leave the description out and AI writes it from the photos (that counts toward the daily limit of free AI helpers). The first photo is the character's picture right away; build_sheet then turns all the photos into a turnaround sheet (costs credits).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.characters.create","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_characters action=create_from_photos","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The character's name, 2 to 40 characters.","type":"string","minLength":2,"maxLength":40},"description":{"description":"How the character looks, in words (up to 1,500 characters): age, build, hair, clothes, colours, art style.","type":"string","maxLength":1500},"photos":{"description":"1 to 5 photos of the same character, each once.","minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"mediaId":{"description":"A picture in your media library (autoclips_media list, upload_link or import_url).","type":"string","pattern":"^[a-fA-F0-9]{24}$"},"view":{"description":"What the photo shows: front, three-quarter, side, back, smiling or other. Leave it out and AI tags it.","type":"string","enum":["front","three-quarter","side","back","smiling","other"]}},"required":["mediaId"],"additionalProperties":false}}},"required":["name","photos"],"additionalProperties":false},"example":{"name":"Grandpa Joe","description":"An elderly man with a white beard and round glasses, in a brown cardigan.","photos":[{"mediaId":"66f7c0ffee00000000000001","view":"front"},{"mediaId":"66f7c0ffee00000000000002","view":"side"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"character":{"type":"object","properties":{"id":{"description":"The character id. Use it to put the character in a V3 video, or with get, update, delete, regenerate_sheet and build_sheet.","type":"string"},"name":{"type":"string"},"description":{"description":"How the character looks, in words. The AI uses it with the sheet.","type":"string"},"sheetUrl":{"description":"The reference sheet picture that keeps the face the same in every scene.","anyOf":[{"type":"string"},{"type":"null"}]},"sheets":{"description":"Every sheet this character has had, oldest first (the last 20). Empty for a character whose sheet has not changed since AutoClips began keeping them. Switching back to one with update (sheetUrl) is free.","type":"array","items":{"type":"object","properties":{"url":{"description":"The sheet picture. Send it as sheetUrl to update to make it the character's sheet again.","type":"string"},"label":{"description":"What made it: the model's name, or \"From your photos\" for a sheet built from photos.","type":"string"},"model":{"description":"The model picked for it (grokImagine, seedream45, krea2Medium, seedream5Pro), or grounded for a sheet built from photos; null when not recorded.","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"generated (drawn from the description) or grounded (built from photos); older sheets can carry the character's source.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"current":{"description":"True for the sheet the character uses now.","type":"boolean"}},"required":["url","label","model","kind","createdAt","current"],"additionalProperties":false}},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"generated (drawn from a description), uploaded (from photos), from-video (saved from a project) or preset (an AutoClips starter character).","type":"string"},"isPreset":{"description":"True for AutoClips starter characters. Everyone can use them; nobody can change them.","type":"boolean"},"style":{"description":"The V3 style it was drawn in, when it was one of the V3 styles.","anyOf":[{"type":"string"},{"type":"null"}]},"photos":{"description":"The photos it was made from (characters made from photos only).","type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"view":{"anyOf":[{"type":"string","enum":["front","three-quarter","side","back","smiling","other"]},{"type":"null"}]}},"required":["url","view"],"additionalProperties":false}},"hasPhotoSheet":{"description":"True once build_sheet has turned the photos into a turnaround sheet.","type":"boolean"},"voice":{"description":"The character's own voice, used when the character speaks in character clips.","anyOf":[{"type":"object","properties":{"voiceId":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string","enum":["library","cloned"]}},"required":["voiceId","name","source"],"additionalProperties":false},{"type":"null"}]},"usageCount":{"description":"How many videos used it.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"canChange":{"description":"You can rename it, describe it, give it a voice, switch back to an earlier sheet or delete it.","type":"boolean"},"canRegenerateSheet":{"description":"regenerate_sheet works for it (characters drawn from a description).","type":"boolean"},"canBuildSheet":{"description":"build_sheet works for it (characters made from photos).","type":"boolean"}},"required":["id","name","description","sheetUrl","sheets","thumbnailUrl","source","isPreset","style","photos","hasPhotoSheet","voice","usageCount","createdAt","updatedAt","canChange","canRegenerateSheet","canBuildSheet"],"additionalProperties":false}},"required":["character"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"character":{"id":"7b3d9e21-4f5a-4c8b-a1d2-3e4f5a6b7c8d","name":"Grandpa Joe","description":"An elderly man with a white beard and round glasses, in a brown cardigan.","sheetUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-grandpa-joe-5e6f7a8b/source-0-1759050000000.jpg","sheets":[],"thumbnailUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-grandpa-joe-5e6f7a8b/source-0-1759050000000.jpg","source":"uploaded","isPreset":false,"style":null,"photos":[{"url":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-grandpa-joe-5e6f7a8b/source-0-1759050000000.jpg","view":"front"},{"url":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-grandpa-joe-5e6f7a8b/source-1-1759050000000.jpg","view":"side"}],"hasPhotoSheet":false,"voice":null,"usageCount":0,"createdAt":"2026-09-20T09:00:00.000Z","updatedAt":"2026-09-25T14:30:00.000Z","canChange":true,"canRegenerateSheet":false,"canBuildSheet":true}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/characters/generate":{"post":{"operationId":"v3_characters_generate","summary":"Make a new character from a description: an AI draws its turnaround sheet. Costs credits; answers with a job.","description":"An AI draws a 2x2 turnaround sheet (front, three-quarter, side, back) from your description and saves the character. Prices: grokImagine 40, seedream45 50, seedream5Pro 50, krea2Medium 40 credits, times your plan's multiplier. Needs a subscription. It runs in the background: follow the job; if the sheet cannot be made the credits are given back. Up to 3 new characters can be drawn at once.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"v3.characters.generate","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"v3_characters action=generate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The character's name, 2 to 40 characters.","type":"string","minLength":2,"maxLength":40},"description":{"description":"How the character looks, in words (10 to 1,500 characters): age, build, hair, clothes, colours, anything distinctive.","type":"string","minLength":10,"maxLength":1500},"style":{"description":"Style: The art style of every picture.\nChoices:\n- realistic-4k — 4k Realistic: 4k Realistic pictures.\n- creepy-toon — Creepy Toon: Creepy Toon pictures.\n- claymation — Claymation: Claymation pictures.\n- cartoon — Cartoon: Cartoon pictures.\n- fantasy-art — Fantasy Art: Fantasy Art pictures.\n- kawaii — Kawaii: Kawaii pictures.\n- cinematic — Cinematic: Cinematic pictures.\n- digital-art — Digital Art: Digital Art pictures.\n- neon-futuristic — Neon Futuristic: Neon Futuristic pictures.\n- comic-book — Comic Book: Comic Book pictures.\n- playground — Playground: Playground pictures.\n- anime — Anime: Anime pictures.\nDefault: realistic, full body (a plain photo look that is none of these styles) (leave it out).","type":"string","enum":["realistic-4k","creepy-toon","claymation","cartoon","fantasy-art","kawaii","cinematic","digital-art","neon-futuristic","comic-book","playground","anime"]},"model":{"description":"Which AI draws the sheet: grokImagine - Fast and sharp (Grok Imagine), 40 credits; seedream45 - Best faces (Seedream 4.5), 50 credits; seedream5Pro - Truest to the description, full body in every view (Seedream 5 Pro), 50 credits; krea2Medium - Most artistic (Krea 2), 40 credits. Plan price multipliers apply. Default: seedream5Pro for a new character (generate); a redraw (regenerate_sheet) uses the model its current sheet was drawn with, or seedream5Pro if that model is not one of these.","type":"string","enum":["grokImagine","seedream45","seedream5Pro","krea2Medium"]},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"required":["name","description"],"additionalProperties":false},"example":{"name":"Maya","description":"A 30-year-old baker with curly red hair tied up, freckles, a flour-dusted green apron over a white shirt."}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job":{"description":"Follow it with autoclips_jobs get (GET /jobs/{id}). When it succeeds, result.character is the character with the sheet this job made (result.sheetUrl); result.sheetIsCurrent is false when a newer sheet has replaced it since.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"character":{"description":"The character as it is now, before the new sheet (null for a new character).","anyOf":[{"type":"object","properties":{"id":{"description":"The character id. Use it to put the character in a V3 video, or with get, update, delete, regenerate_sheet and build_sheet.","type":"string"},"name":{"type":"string"},"description":{"description":"How the character looks, in words. The AI uses it with the sheet.","type":"string"},"sheetUrl":{"description":"The reference sheet picture that keeps the face the same in every scene.","anyOf":[{"type":"string"},{"type":"null"}]},"sheets":{"description":"Every sheet this character has had, oldest first (the last 20). Empty for a character whose sheet has not changed since AutoClips began keeping them. Switching back to one with update (sheetUrl) is free.","type":"array","items":{"type":"object","properties":{"url":{"description":"The sheet picture. Send it as sheetUrl to update to make it the character's sheet again.","type":"string"},"label":{"description":"What made it: the model's name, or \"From your photos\" for a sheet built from photos.","type":"string"},"model":{"description":"The model picked for it (grokImagine, seedream45, krea2Medium, seedream5Pro), or grounded for a sheet built from photos; null when not recorded.","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"generated (drawn from the description) or grounded (built from photos); older sheets can carry the character's source.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"current":{"description":"True for the sheet the character uses now.","type":"boolean"}},"required":["url","label","model","kind","createdAt","current"],"additionalProperties":false}},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"generated (drawn from a description), uploaded (from photos), from-video (saved from a project) or preset (an AutoClips starter character).","type":"string"},"isPreset":{"description":"True for AutoClips starter characters. Everyone can use them; nobody can change them.","type":"boolean"},"style":{"description":"The V3 style it was drawn in, when it was one of the V3 styles.","anyOf":[{"type":"string"},{"type":"null"}]},"photos":{"description":"The photos it was made from (characters made from photos only).","type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"view":{"anyOf":[{"type":"string","enum":["front","three-quarter","side","back","smiling","other"]},{"type":"null"}]}},"required":["url","view"],"additionalProperties":false}},"hasPhotoSheet":{"description":"True once build_sheet has turned the photos into a turnaround sheet.","type":"boolean"},"voice":{"description":"The character's own voice, used when the character speaks in character clips.","anyOf":[{"type":"object","properties":{"voiceId":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string","enum":["library","cloned"]}},"required":["voiceId","name","source"],"additionalProperties":false},{"type":"null"}]},"usageCount":{"description":"How many videos used it.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"canChange":{"description":"You can rename it, describe it, give it a voice, switch back to an earlier sheet or delete it.","type":"boolean"},"canRegenerateSheet":{"description":"regenerate_sheet works for it (characters drawn from a description).","type":"boolean"},"canBuildSheet":{"description":"build_sheet works for it (characters made from photos).","type":"boolean"}},"required":["id","name","description","sheetUrl","sheets","thumbnailUrl","source","isPreset","style","photos","hasPhotoSheet","voice","usageCount","createdAt","updatedAt","canChange","canRegenerateSheet","canBuildSheet"],"additionalProperties":false},{"type":"null"}]}},"required":["job","character"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"job":{"id":"job_0192f1a2b3c4d5e6f7a8b9c0","product":"v3","kind":"v3.character_sheet","resource":{"type":"character_run","id":"chrun_3f9a1c2b4d5e6f708192a3b4"},"status":"running","step":"Drawing the character sheet","progress":null,"result":null,"error":null,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","finishedAt":null,"poll_after_seconds":15},"character":null}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/characters/{characterId}":{"get":{"operationId":"v3_characters_get","summary":"Get one of your characters, or a starter character, by its id.","description":"Get one of your characters, or a starter character, by its id.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"v3.characters.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_characters action=get","parameters":[{"name":"characterId","in":"path","required":true,"schema":{"description":"The character id, from list.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The character id, from list.","example":"0f8c2a4e-6b1d-4c3e-9a7f-2d5e8b1c4a90"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"character":{"type":"object","properties":{"id":{"description":"The character id. Use it to put the character in a V3 video, or with get, update, delete, regenerate_sheet and build_sheet.","type":"string"},"name":{"type":"string"},"description":{"description":"How the character looks, in words. The AI uses it with the sheet.","type":"string"},"sheetUrl":{"description":"The reference sheet picture that keeps the face the same in every scene.","anyOf":[{"type":"string"},{"type":"null"}]},"sheets":{"description":"Every sheet this character has had, oldest first (the last 20). Empty for a character whose sheet has not changed since AutoClips began keeping them. Switching back to one with update (sheetUrl) is free.","type":"array","items":{"type":"object","properties":{"url":{"description":"The sheet picture. Send it as sheetUrl to update to make it the character's sheet again.","type":"string"},"label":{"description":"What made it: the model's name, or \"From your photos\" for a sheet built from photos.","type":"string"},"model":{"description":"The model picked for it (grokImagine, seedream45, krea2Medium, seedream5Pro), or grounded for a sheet built from photos; null when not recorded.","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"generated (drawn from the description) or grounded (built from photos); older sheets can carry the character's source.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"current":{"description":"True for the sheet the character uses now.","type":"boolean"}},"required":["url","label","model","kind","createdAt","current"],"additionalProperties":false}},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"generated (drawn from a description), uploaded (from photos), from-video (saved from a project) or preset (an AutoClips starter character).","type":"string"},"isPreset":{"description":"True for AutoClips starter characters. Everyone can use them; nobody can change them.","type":"boolean"},"style":{"description":"The V3 style it was drawn in, when it was one of the V3 styles.","anyOf":[{"type":"string"},{"type":"null"}]},"photos":{"description":"The photos it was made from (characters made from photos only).","type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"view":{"anyOf":[{"type":"string","enum":["front","three-quarter","side","back","smiling","other"]},{"type":"null"}]}},"required":["url","view"],"additionalProperties":false}},"hasPhotoSheet":{"description":"True once build_sheet has turned the photos into a turnaround sheet.","type":"boolean"},"voice":{"description":"The character's own voice, used when the character speaks in character clips.","anyOf":[{"type":"object","properties":{"voiceId":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string","enum":["library","cloned"]}},"required":["voiceId","name","source"],"additionalProperties":false},{"type":"null"}]},"usageCount":{"description":"How many videos used it.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"canChange":{"description":"You can rename it, describe it, give it a voice, switch back to an earlier sheet or delete it.","type":"boolean"},"canRegenerateSheet":{"description":"regenerate_sheet works for it (characters drawn from a description).","type":"boolean"},"canBuildSheet":{"description":"build_sheet works for it (characters made from photos).","type":"boolean"}},"required":["id","name","description","sheetUrl","sheets","thumbnailUrl","source","isPreset","style","photos","hasPhotoSheet","voice","usageCount","createdAt","updatedAt","canChange","canRegenerateSheet","canBuildSheet"],"additionalProperties":false}},"required":["character"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"character":{"id":"0f8c2a4e-6b1d-4c3e-9a7f-2d5e8b1c4a90","name":"Maya","description":"A 30-year-old baker with curly red hair tied up, freckles, a flour-dusted green apron over a white shirt.","sheetUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1759050000000.jpg","sheets":[{"url":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1758358800000.jpg","label":"Fast and sharp (Grok Imagine)","model":"grokImagine","kind":"generated","createdAt":"2026-09-20T09:00:00.000Z","current":false},{"url":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1759050000000.jpg","label":"Most artistic (Krea 2)","model":"krea2Medium","kind":"generated","createdAt":"2026-09-25T14:30:00.000Z","current":true}],"thumbnailUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1759050000000.jpg","source":"generated","isPreset":false,"style":null,"photos":[],"hasPhotoSheet":false,"voice":null,"usageCount":2,"createdAt":"2026-09-20T09:00:00.000Z","updatedAt":"2026-09-25T14:30:00.000Z","canChange":true,"canRegenerateSheet":true,"canBuildSheet":false}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"v3_characters_update","summary":"Rename a character, change its description, give it a voice (or remove it), or switch back to an earlier sheet.","description":"Send only what changes. voice is a voice id or name from autoclips_voices: any library voice or one of your own cloned voices; null removes the voice. A library voice is checked with the voice library when it is set, so it cannot be set while the library is unreachable (your own cloned voices still can). sheetUrl switches the character back to one of its earlier sheets (sheets in get), free, like picking an earlier result in the app. A new description is used the next time the sheet is drawn. Starter characters cannot be changed.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.characters.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_characters action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The character's name, 2 to 40 characters.","type":"string","minLength":2,"maxLength":40},"description":{"description":"How the character looks, in words (up to 1,500 characters): age, build, hair, clothes, colours, art style.","type":"string","maxLength":1500},"voice":{"description":"A voice id or name for the character (autoclips_voices: any library voice or your own cloned voice), or null to remove it.","anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"sheetUrl":{"description":"Make one of the character's earlier sheets its sheet again: a url from its sheets (get). Free.","type":"string","minLength":1,"maxLength":2048}},"additionalProperties":false},"example":{"voice":"Josh"}}}},"parameters":[{"name":"characterId","in":"path","required":true,"schema":{"description":"The character id, from list.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The character id, from list.","example":"0f8c2a4e-6b1d-4c3e-9a7f-2d5e8b1c4a90"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"character":{"type":"object","properties":{"id":{"description":"The character id. Use it to put the character in a V3 video, or with get, update, delete, regenerate_sheet and build_sheet.","type":"string"},"name":{"type":"string"},"description":{"description":"How the character looks, in words. The AI uses it with the sheet.","type":"string"},"sheetUrl":{"description":"The reference sheet picture that keeps the face the same in every scene.","anyOf":[{"type":"string"},{"type":"null"}]},"sheets":{"description":"Every sheet this character has had, oldest first (the last 20). Empty for a character whose sheet has not changed since AutoClips began keeping them. Switching back to one with update (sheetUrl) is free.","type":"array","items":{"type":"object","properties":{"url":{"description":"The sheet picture. Send it as sheetUrl to update to make it the character's sheet again.","type":"string"},"label":{"description":"What made it: the model's name, or \"From your photos\" for a sheet built from photos.","type":"string"},"model":{"description":"The model picked for it (grokImagine, seedream45, krea2Medium, seedream5Pro), or grounded for a sheet built from photos; null when not recorded.","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"generated (drawn from the description) or grounded (built from photos); older sheets can carry the character's source.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"current":{"description":"True for the sheet the character uses now.","type":"boolean"}},"required":["url","label","model","kind","createdAt","current"],"additionalProperties":false}},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"generated (drawn from a description), uploaded (from photos), from-video (saved from a project) or preset (an AutoClips starter character).","type":"string"},"isPreset":{"description":"True for AutoClips starter characters. Everyone can use them; nobody can change them.","type":"boolean"},"style":{"description":"The V3 style it was drawn in, when it was one of the V3 styles.","anyOf":[{"type":"string"},{"type":"null"}]},"photos":{"description":"The photos it was made from (characters made from photos only).","type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"view":{"anyOf":[{"type":"string","enum":["front","three-quarter","side","back","smiling","other"]},{"type":"null"}]}},"required":["url","view"],"additionalProperties":false}},"hasPhotoSheet":{"description":"True once build_sheet has turned the photos into a turnaround sheet.","type":"boolean"},"voice":{"description":"The character's own voice, used when the character speaks in character clips.","anyOf":[{"type":"object","properties":{"voiceId":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string","enum":["library","cloned"]}},"required":["voiceId","name","source"],"additionalProperties":false},{"type":"null"}]},"usageCount":{"description":"How many videos used it.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"canChange":{"description":"You can rename it, describe it, give it a voice, switch back to an earlier sheet or delete it.","type":"boolean"},"canRegenerateSheet":{"description":"regenerate_sheet works for it (characters drawn from a description).","type":"boolean"},"canBuildSheet":{"description":"build_sheet works for it (characters made from photos).","type":"boolean"}},"required":["id","name","description","sheetUrl","sheets","thumbnailUrl","source","isPreset","style","photos","hasPhotoSheet","voice","usageCount","createdAt","updatedAt","canChange","canRegenerateSheet","canBuildSheet"],"additionalProperties":false},"changed":{"type":"array","items":{"type":"string","enum":["name","description","voice","sheet"]}}},"required":["character","changed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"character":{"id":"0f8c2a4e-6b1d-4c3e-9a7f-2d5e8b1c4a90","name":"Maya","description":"A 30-year-old baker with curly red hair tied up, freckles, a flour-dusted green apron over a white shirt.","sheetUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1759050000000.jpg","sheets":[{"url":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1758358800000.jpg","label":"Fast and sharp (Grok Imagine)","model":"grokImagine","kind":"generated","createdAt":"2026-09-20T09:00:00.000Z","current":false},{"url":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1759050000000.jpg","label":"Most artistic (Krea 2)","model":"krea2Medium","kind":"generated","createdAt":"2026-09-25T14:30:00.000Z","current":true}],"thumbnailUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1759050000000.jpg","source":"generated","isPreset":false,"style":null,"photos":[],"hasPhotoSheet":false,"voice":{"voiceId":"TxGEqnHWrfWFTfGW9XjX","name":"Josh","source":"library"},"usageCount":2,"createdAt":"2026-09-20T09:00:00.000Z","updatedAt":"2026-09-25T14:30:00.000Z","canChange":true,"canRegenerateSheet":true,"canBuildSheet":false},"changed":["voice"]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"v3_characters_delete","summary":"Delete one of your characters. Videos already made keep it; starter characters cannot be deleted.","description":"Removes the character from your library, so it can no longer be picked for new videos. Videos and projects that already use it keep their pictures. While a new sheet for the character is being made, wait for its job to finish first. A character one of your automations casts cannot be deleted (conflict, reason in_automation, with the automations' names): take it out of them in the app first.\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"v3.characters.delete","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_characters action=delete","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"characterId","in":"path","required":true,"schema":{"description":"The character id, from list.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The character id, from list.","example":"0f8c2a4e-6b1d-4c3e-9a7f-2d5e8b1c4a90"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"deleted":{"type":"boolean"}},"required":["id","name","deleted"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"id":"0f8c2a4e-6b1d-4c3e-9a7f-2d5e8b1c4a90","name":"Maya","deleted":true}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/characters/{characterId}/build-sheet":{"post":{"operationId":"v3_characters_build_sheet","summary":"Turn a photo character's photos into a turnaround sheet. Costs credits; answers with a job.","description":"For characters made with create_from_photos. An AI draws a 2x2 turnaround sheet that looks like the person in the photos and makes it the character's picture. 50 credits, times your plan's multiplier, given back if it fails (for example when the photos are flagged). Can be run again. Needs a subscription.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"v3.characters.build_sheet","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"v3_characters action=build_sheet","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"characterId","in":"path","required":true,"schema":{"description":"The character id, from list.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The character id, from list.","example":"7b3d9e21-4f5a-4c8b-a1d2-3e4f5a6b7c8d"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job":{"description":"Follow it with autoclips_jobs get (GET /jobs/{id}). When it succeeds, result.character is the character with the sheet this job made (result.sheetUrl); result.sheetIsCurrent is false when a newer sheet has replaced it since.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"character":{"description":"The character as it is now, before the new sheet (null for a new character).","anyOf":[{"type":"object","properties":{"id":{"description":"The character id. Use it to put the character in a V3 video, or with get, update, delete, regenerate_sheet and build_sheet.","type":"string"},"name":{"type":"string"},"description":{"description":"How the character looks, in words. The AI uses it with the sheet.","type":"string"},"sheetUrl":{"description":"The reference sheet picture that keeps the face the same in every scene.","anyOf":[{"type":"string"},{"type":"null"}]},"sheets":{"description":"Every sheet this character has had, oldest first (the last 20). Empty for a character whose sheet has not changed since AutoClips began keeping them. Switching back to one with update (sheetUrl) is free.","type":"array","items":{"type":"object","properties":{"url":{"description":"The sheet picture. Send it as sheetUrl to update to make it the character's sheet again.","type":"string"},"label":{"description":"What made it: the model's name, or \"From your photos\" for a sheet built from photos.","type":"string"},"model":{"description":"The model picked for it (grokImagine, seedream45, krea2Medium, seedream5Pro), or grounded for a sheet built from photos; null when not recorded.","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"generated (drawn from the description) or grounded (built from photos); older sheets can carry the character's source.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"current":{"description":"True for the sheet the character uses now.","type":"boolean"}},"required":["url","label","model","kind","createdAt","current"],"additionalProperties":false}},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"generated (drawn from a description), uploaded (from photos), from-video (saved from a project) or preset (an AutoClips starter character).","type":"string"},"isPreset":{"description":"True for AutoClips starter characters. Everyone can use them; nobody can change them.","type":"boolean"},"style":{"description":"The V3 style it was drawn in, when it was one of the V3 styles.","anyOf":[{"type":"string"},{"type":"null"}]},"photos":{"description":"The photos it was made from (characters made from photos only).","type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"view":{"anyOf":[{"type":"string","enum":["front","three-quarter","side","back","smiling","other"]},{"type":"null"}]}},"required":["url","view"],"additionalProperties":false}},"hasPhotoSheet":{"description":"True once build_sheet has turned the photos into a turnaround sheet.","type":"boolean"},"voice":{"description":"The character's own voice, used when the character speaks in character clips.","anyOf":[{"type":"object","properties":{"voiceId":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string","enum":["library","cloned"]}},"required":["voiceId","name","source"],"additionalProperties":false},{"type":"null"}]},"usageCount":{"description":"How many videos used it.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"canChange":{"description":"You can rename it, describe it, give it a voice, switch back to an earlier sheet or delete it.","type":"boolean"},"canRegenerateSheet":{"description":"regenerate_sheet works for it (characters drawn from a description).","type":"boolean"},"canBuildSheet":{"description":"build_sheet works for it (characters made from photos).","type":"boolean"}},"required":["id","name","description","sheetUrl","sheets","thumbnailUrl","source","isPreset","style","photos","hasPhotoSheet","voice","usageCount","createdAt","updatedAt","canChange","canRegenerateSheet","canBuildSheet"],"additionalProperties":false},{"type":"null"}]}},"required":["job","character"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"job":{"id":"job_0192f1a2b3c4d5e6f7a8b9c0","product":"v3","kind":"v3.character_sheet","resource":{"type":"character","id":"7b3d9e21-4f5a-4c8b-a1d2-3e4f5a6b7c8d"},"status":"running","step":"Building the sheet from your photos","progress":null,"result":null,"error":null,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","finishedAt":null,"poll_after_seconds":15},"character":{"id":"7b3d9e21-4f5a-4c8b-a1d2-3e4f5a6b7c8d","name":"Grandpa Joe","description":"An elderly man with a white beard and round glasses, in a brown cardigan.","sheetUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-grandpa-joe-5e6f7a8b/source-0-1759050000000.jpg","sheets":[],"thumbnailUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-grandpa-joe-5e6f7a8b/source-0-1759050000000.jpg","source":"uploaded","isPreset":false,"style":null,"photos":[{"url":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-grandpa-joe-5e6f7a8b/source-0-1759050000000.jpg","view":"front"},{"url":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-grandpa-joe-5e6f7a8b/source-1-1759050000000.jpg","view":"side"}],"hasPhotoSheet":false,"voice":null,"usageCount":0,"createdAt":"2026-09-20T09:00:00.000Z","updatedAt":"2026-09-25T14:30:00.000Z","canChange":true,"canRegenerateSheet":false,"canBuildSheet":true}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/characters/{characterId}/regenerate-sheet":{"post":{"operationId":"v3_characters_regenerate_sheet","summary":"Redraw the sheet of a character made from a description. Costs credits; answers with a job.","description":"For characters made with generate. Uses the same name and description (change them with update first), the model you pick or the one it was drawn with, and the style you pick (for example the look of the video it will be in) or the one it was last drawn in. Same prices as generate. The old sheet stays in videos already made and in the character's sheets, so update can switch back to it for free. Needs a subscription.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"v3.characters.regenerate_sheet","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"v3_characters action=regenerate_sheet","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"description":"Which AI draws the sheet: grokImagine - Fast and sharp (Grok Imagine), 40 credits; seedream45 - Best faces (Seedream 4.5), 50 credits; seedream5Pro - Truest to the description, full body in every view (Seedream 5 Pro), 50 credits; krea2Medium - Most artistic (Krea 2), 40 credits. Plan price multipliers apply. Default: seedream5Pro for a new character (generate); a redraw (regenerate_sheet) uses the model its current sheet was drawn with, or seedream5Pro if that model is not one of these.","type":"string","enum":["grokImagine","seedream45","seedream5Pro","krea2Medium"]},"style":{"description":"Style: The art style of every picture.\nChoices:\n- realistic-4k — 4k Realistic: 4k Realistic pictures.\n- creepy-toon — Creepy Toon: Creepy Toon pictures.\n- claymation — Claymation: Claymation pictures.\n- cartoon — Cartoon: Cartoon pictures.\n- fantasy-art — Fantasy Art: Fantasy Art pictures.\n- kawaii — Kawaii: Kawaii pictures.\n- cinematic — Cinematic: Cinematic pictures.\n- digital-art — Digital Art: Digital Art pictures.\n- neon-futuristic — Neon Futuristic: Neon Futuristic pictures.\n- comic-book — Comic Book: Comic Book pictures.\n- playground — Playground: Playground pictures.\n- anime — Anime: Anime pictures.\nDefault: the style the character was last drawn in (leave it out).","type":"string","enum":["realistic-4k","creepy-toon","claymation","cartoon","fantasy-art","kawaii","cinematic","digital-art","neon-futuristic","comic-book","playground","anime"]},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{"model":"seedream45"}}}},"parameters":[{"name":"characterId","in":"path","required":true,"schema":{"description":"The character id, from list.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The character id, from list.","example":"0f8c2a4e-6b1d-4c3e-9a7f-2d5e8b1c4a90"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job":{"description":"Follow it with autoclips_jobs get (GET /jobs/{id}). When it succeeds, result.character is the character with the sheet this job made (result.sheetUrl); result.sheetIsCurrent is false when a newer sheet has replaced it since.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"character":{"description":"The character as it is now, before the new sheet (null for a new character).","anyOf":[{"type":"object","properties":{"id":{"description":"The character id. Use it to put the character in a V3 video, or with get, update, delete, regenerate_sheet and build_sheet.","type":"string"},"name":{"type":"string"},"description":{"description":"How the character looks, in words. The AI uses it with the sheet.","type":"string"},"sheetUrl":{"description":"The reference sheet picture that keeps the face the same in every scene.","anyOf":[{"type":"string"},{"type":"null"}]},"sheets":{"description":"Every sheet this character has had, oldest first (the last 20). Empty for a character whose sheet has not changed since AutoClips began keeping them. Switching back to one with update (sheetUrl) is free.","type":"array","items":{"type":"object","properties":{"url":{"description":"The sheet picture. Send it as sheetUrl to update to make it the character's sheet again.","type":"string"},"label":{"description":"What made it: the model's name, or \"From your photos\" for a sheet built from photos.","type":"string"},"model":{"description":"The model picked for it (grokImagine, seedream45, krea2Medium, seedream5Pro), or grounded for a sheet built from photos; null when not recorded.","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"generated (drawn from the description) or grounded (built from photos); older sheets can carry the character's source.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"current":{"description":"True for the sheet the character uses now.","type":"boolean"}},"required":["url","label","model","kind","createdAt","current"],"additionalProperties":false}},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"generated (drawn from a description), uploaded (from photos), from-video (saved from a project) or preset (an AutoClips starter character).","type":"string"},"isPreset":{"description":"True for AutoClips starter characters. Everyone can use them; nobody can change them.","type":"boolean"},"style":{"description":"The V3 style it was drawn in, when it was one of the V3 styles.","anyOf":[{"type":"string"},{"type":"null"}]},"photos":{"description":"The photos it was made from (characters made from photos only).","type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"view":{"anyOf":[{"type":"string","enum":["front","three-quarter","side","back","smiling","other"]},{"type":"null"}]}},"required":["url","view"],"additionalProperties":false}},"hasPhotoSheet":{"description":"True once build_sheet has turned the photos into a turnaround sheet.","type":"boolean"},"voice":{"description":"The character's own voice, used when the character speaks in character clips.","anyOf":[{"type":"object","properties":{"voiceId":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string","enum":["library","cloned"]}},"required":["voiceId","name","source"],"additionalProperties":false},{"type":"null"}]},"usageCount":{"description":"How many videos used it.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"canChange":{"description":"You can rename it, describe it, give it a voice, switch back to an earlier sheet or delete it.","type":"boolean"},"canRegenerateSheet":{"description":"regenerate_sheet works for it (characters drawn from a description).","type":"boolean"},"canBuildSheet":{"description":"build_sheet works for it (characters made from photos).","type":"boolean"}},"required":["id","name","description","sheetUrl","sheets","thumbnailUrl","source","isPreset","style","photos","hasPhotoSheet","voice","usageCount","createdAt","updatedAt","canChange","canRegenerateSheet","canBuildSheet"],"additionalProperties":false},{"type":"null"}]}},"required":["job","character"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"job":{"id":"job_0192f1a2b3c4d5e6f7a8b9c0","product":"v3","kind":"v3.character_sheet","resource":{"type":"character","id":"0f8c2a4e-6b1d-4c3e-9a7f-2d5e8b1c4a90"},"status":"running","step":"Redrawing the character sheet","progress":null,"result":null,"error":null,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","finishedAt":null,"poll_after_seconds":15},"character":{"id":"0f8c2a4e-6b1d-4c3e-9a7f-2d5e8b1c4a90","name":"Maya","description":"A 30-year-old baker with curly red hair tied up, freckles, a flour-dusted green apron over a white shirt.","sheetUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1759050000000.jpg","sheets":[{"url":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1758358800000.jpg","label":"Fast and sharp (Grok Imagine)","model":"grokImagine","kind":"generated","createdAt":"2026-09-20T09:00:00.000Z","current":false},{"url":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1759050000000.jpg","label":"Most artistic (Krea 2)","model":"krea2Medium","kind":"generated","createdAt":"2026-09-25T14:30:00.000Z","current":true}],"thumbnailUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-maya-1a2b3c4d/sheet-1759050000000.jpg","source":"generated","isPreset":false,"style":null,"photos":[],"hasPhotoSheet":false,"voice":null,"usageCount":2,"createdAt":"2026-09-20T09:00:00.000Z","updatedAt":"2026-09-25T14:30:00.000Z","canChange":true,"canRegenerateSheet":true,"canBuildSheet":false}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects":{"get":{"operationId":"v3_projects_list","summary":"Your V3 projects, most recently changed first, with their status. Filter by status or words in the title.","description":"Lists your V3 cinematic story projects, most recently changed first. Filter with status (for example completed or failed) and search (words in the title). Page with limit and next_cursor. A page filtered by search looks through up to 500 projects, so it can hold fewer than limit items while has_more is true.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"v3.projects.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_projects action=list","parameters":[{"name":"limit","in":"query","required":false,"schema":{"description":"How many items to return (1–100, default 20).","type":"integer","minimum":1,"maximum":100},"description":"How many items to return (1–100, default 20).","example":10},{"name":"cursor","in":"query","required":false,"schema":{"description":"The next_cursor from the previous page.","type":"string","maxLength":512},"description":"The next_cursor from the previous page."},{"name":"status","in":"query","required":false,"schema":{"description":"Only projects with this status: draft (Draft: settings saved, no script yet); generating-script (Writing the script); script-ready (Script ready to review); generating-assets (Making pictures, voice and music); assets-ready (Pictures and voice ready); generating-edl (Putting the timeline together); edl-ready (Ready to render); rendering (Rendering the video); completed (Video ready); failed (Stopped with a problem).","type":"string","enum":["draft","generating-script","script-ready","generating-assets","assets-ready","generating-edl","edl-ready","rendering","completed","failed"]},"description":"Only projects with this status: draft (Draft: settings saved, no script yet); generating-script (Writing the script); script-ready (Script ready to review); generating-assets (Making pictures, voice and music); assets-ready (Pictures and voice ready); generating-edl (Putting the timeline together); edl-ready (Ready to render); rendering (Rendering the video); completed (Video ready); failed (Stopped with a problem).","example":"completed"},{"name":"search","in":"query","required":false,"schema":{"description":"Only projects whose title contains these words (not case sensitive).","type":"string","minLength":1,"maxLength":80},"description":"Only projects whose title contains these words (not case sensitive).","example":"volcano"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"description":"Where the project is: draft, generating-script, script-ready, generating-assets, assets-ready, generating-edl, edl-ready, rendering, completed, failed.","type":"string"},"stage":{"description":"The status in plain words.","type":"string"},"progress":{"type":"number"},"problem":{"description":"Why it stopped, when status is failed.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"settings":{"description":"The project's settings, in the same words the create and update actions take.","type":"object","properties":{},"additionalProperties":{}},"series":{"description":"Its place in a series. To make the next part, quick_create with series.previousProjectId set to this project's id: it starts from this project's settings, as the app's \"Create Part N\" does. The step-by-step way (a new draft from create, then v3_script generate with series) carries on the story only: the draft starts from the default settings (length, shape, language, look, featured characters), not this project's, unless you send them to create.","type":"object","properties":{"part":{"description":"Which part of a series this video is (1 for a video on its own).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"previousProjectId":{"description":"The project of the part before, when this one continues it.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["part","previousProjectId"],"additionalProperties":{}},"input":{"type":"object","properties":{},"additionalProperties":{}},"counts":{"type":"object","properties":{},"additionalProperties":{}},"video":{"description":"The finished video, once rendered.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"render":{"type":"object","properties":{},"additionalProperties":{}},"pipeline":{"description":"Quick Create progress, for projects made with quick_create. stalled is true when a run reads running but its server stopped (no sign of it for 5 minutes): retry carries it on.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"revisions":{"type":"object","properties":{},"additionalProperties":{}},"credits":{"description":"Credits already paid for the script and for the pictures and voice.","type":"object","properties":{},"additionalProperties":{}},"isDemo":{"type":"boolean"},"links":{"description":"Where to open the project in the app.","type":"object","properties":{},"additionalProperties":{}}},"required":["id","product","title","status","stage","progress","problem","createdAt","updatedAt","settings","series","input","counts","video","render","pipeline","revisions","credits","isDemo","links"],"additionalProperties":{}}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"has_more":{"type":"boolean"}},"required":["items","next_cursor","has_more"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"v3_projects_create","summary":"Make a free V3 draft from a topic, your story or a Reddit post, with its settings. Nothing is generated yet.","description":"Creates a draft project with every setting (see autoclips_options, product v3). Send exactly one story source: topic, story { title?, text } or redditUrl (its text is imported now). Leave settings out for the defaults, or send a recipe (quick, standard, cinematic) to fill several at once. The voice model left out is your account's voice model; movement left out is the same default as Quick Create and Ask (every scene moves on AutoClips for a short, 9:16 up to 3 minutes; stills otherwise; the create page opens a longer or wider video with its opening scene moving instead: send animation opening for that), and it follows a later length or shape you set with update until you send animation. A pasted or Reddit story is made at the length it needs when that is longer than the one picked (the length of what is read aloud: a story written as a script is narrated without its formatting; the answer's meta.notes says so). A story gets the AI hook intro unless hookIntro is false; a topic can end on a cliffhanger (cliffhanger). Nothing is generated and nothing is charged: next, write the script with v3_script generate. characterIds adds up to 4 saved characters (turns consistent characters on). publishing switches on auto-posting once the video is rendered: that needs the publish permission, and AI apps ask the user first. Headline and pop-up text (motionText) is on unless you send false; it shows on 9:16 videos only. Your watermark (watermarkType text or image, with its colours, place, size and the seconds it shows) and your outro (outroId, an end card from autoclips_outros, paid plans only) are added when the video is rendered; a picture watermark is one of your pictures, by watermarkMediaId. A draft starts from the default settings, never from another project's: for the next part of a series that keeps the previous part's settings, use quick_create with series. Sending the same request again with the same Idempotency-Key hands back the same draft.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.projects.create","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_projects action=create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"topic":{"description":"What the video is about, in a sentence or two. The writer turns it into a story. Send exactly one of topic, story or redditUrl.","type":"string","minLength":3,"maxLength":2000},"story":{"description":"Your own story, narrated word for word (a script without its formatting). Send exactly one of topic, story or redditUrl.","type":"object","properties":{"title":{"description":"The story's title.","type":"string","maxLength":200},"text":{"description":"The story, read out word for word (50 to 50,000 characters). A story written as a script is narrated without most of its formatting: timestamps, scene headings (\"Scene 2: …\", \"INT. …\"), camera and edit notes (\"Wide shot:\", \"Cut to:\"), sound and music note lines (\"SFX: …\") and speaker names before a colon (\"AIKO: …\") are left out, and so is an acting note in brackets such as (whispering) on its own line, after the name, or opening a line in three words or fewer (a voice model that performs audio tags may get it as a tag). Still read aloud: a name on a line of its own, a lone \"Name:\" in plain prose, and a note inside a sentence or longer than three words. Its length is what is read aloud.","type":"string","minLength":50,"maxLength":50000}},"required":["text"],"additionalProperties":false},"redditUrl":{"description":"A Reddit post to narrate word for word (any script formatting in it is not read aloud); its title and text are imported. Send exactly one of topic, story or redditUrl.","type":"string","maxLength":500,"pattern":"^https:\\/\\/(?:www\\.|old\\.|new\\.)?reddit\\.com\\/r\\/[A-Za-z0-9_]{2,40}\\/comments\\/[A-Za-z0-9]{3,20}(?:\\/[^\\s?#]*)?(?:\\?[^\\s#]*)?$"},"recipe":{"description":"Recipe: A shortcut that fills in several settings at once, like the three cards in the app. Any setting you also send wins over the recipe. Like a card in the app, a recipe is fitted to your account and video: a length above your plan's longest is cut to it, Pro Max movement on a 1:1 video is made on AutoClips instead, and with saved characters a picture maker without consistent characters is swapped for one with them. The answer's notes say what was changed.\nChoices:\n- quick — Quick: Cheapest way to see the idea work: 60 s, standard writer, stills, lowest-cost pictures.\n- standard — Standard: What most finished videos use: 60 s, max writer, every scene moves on AutoClips with its clips made straight from the script, Grok pictures, no consistent characters.\n- cinematic — Cinematic: Every scene moves: 3 min, max writer, premium sound, Pro Max clips, Seedream pictures, consistent characters.\nDefault: No recipe (leave it out).","type":"string","enum":["quick","standard","cinematic"]},"category":{"description":"Category: The kind of story. It shapes the writing, the moods, the music and the look. Use \"general\" if unsure.\nChoices:\n- horror — Horror & Dark Facts: Creepy stories, dark history, unsettling facts\n- science — Science & Nature: Scientific discoveries, natural phenomena, how things work\n- history — History & Ancient Mysteries: Ancient civilizations, historical events, mysteries from the past\n- crime — Crime & Mystery: True crime, mysteries, forensics, detective stories\n- space — Space & Cosmos: Astronomy, space exploration, cosmic mysteries\n- nature — Animals & Wildlife: Animal facts, wildlife, evolution, ecosystems\n- travel — Travel & Culture: Destinations, nightlife, cultural experiences, world exploration\n- food — Food & Cuisine: Cooking, street food, food science, culinary traditions\n- technology — Technology: AI, gadgets, future tech, digital world, cybersecurity\n- psychology — Psychology & Mind: Human behavior, mental health, cognitive biases, social experiments\n- mythology — Mythology & Legends: Gods, mythical creatures, ancient legends, folklore\n- general — General: Any topic — adapts style to your content automatically\nDefault: general.","type":"string","enum":["horror","science","history","crime","space","nature","travel","food","technology","psychology","mythology","general"]},"durationSeconds":{"description":"How long the video is meant to run. The script is written for this length and charged for it. Everything after the script is priced at the length the written script really runs, which is often a little longer or shorter: narration 60 credits a minute, rendering the finished video 30 credits a minute, and pictures, clips and sound effects by that length. Made step by step, generate_assets shows that price before it charges; Quick Create charges it within the limit you approved. A recording that runs shorter gets the difference back. Your plan sets the longest length you can pick. One of 60, 65, 75, 90, 100, 120, 180, 300, 600, 900, 1200 seconds, as a number (60) or as the options' text id (\"60\").","anyOf":[{"type":"number","enum":[60,65,75,90,100,120,180,300,600,900,1200]},{"type":"string","pattern":"^(?:60|65|75|90|100|120|180|300|600|900|1200)$"}]},"aspectRatio":{"description":"Shape: The frame of the video.\nChoices:\n- 9:16 — Tall 9:16: TikTok, Reels and Shorts.\n- 16:9 — Wide 16:9: YouTube.\n- 1:1 — Square 1:1: Instagram feed.\nDefault: 9:16.","type":"string","enum":["9:16","16:9","1:1"]},"imageModel":{"description":"Picture maker: Which model makes the pictures. It sets the look, the speed and the price per picture.\nChoices:\n- grokImagine — Fast and sharp (Grok Imagine): High quality and quick. Supports consistent characters. (20 credits per picture (doubled with consistent characters))\n- seedream5Flash — Sharp for less (Seedream 5 Flash): Sharp pictures at a low price. Supports consistent characters. (12.5 credits per picture (doubled with consistent characters))\n- zImageTurbo — Lowest cost (Z-Image Turbo): The most affordable pictures. No consistent characters. (6.25 credits per picture)\n- fluxSchnell — Best value (Flux 2 Turbo): Good quality for the price. Supports consistent characters. (12.5 credits per picture (doubled with consistent characters))\n- fluxDev — All-rounder (Flux 2): Solid quality for most topics. (18.75 credits per picture (doubled with consistent characters))\n- krea2Medium — Most artistic (Krea 2): Striking, artistic looks. (20 credits per picture (25 with consistent characters))\n- seedream45 — Best faces (Seedream 4.5): The steadiest faces and characters. Slower. (25 credits per picture (doubled with consistent characters))\n- fluxPro — Highest detail (Flux 2 Pro): The most detail per picture. (25 credits per picture (doubled with consistent characters))\n- nanoBanana2 — Follows the prompt (Nano Banana 2): Closest to what the script asks for, 2K pictures. The most expensive. (72 credits per picture (doubled with consistent characters))\n- webSearch — Real photos (web search): Real photos found on the web instead of generated pictures. No consistent characters. (6.25 credits per picture)\nDefault: grokImagine.","type":"string","enum":["grokImagine","seedream5Flash","zImageTurbo","fluxSchnell","fluxDev","krea2Medium","seedream45","fluxPro","nanoBanana2","webSearch"]},"style":{"description":"Style: The art style of every picture.\nChoices:\n- realistic-4k — 4k Realistic: 4k Realistic pictures.\n- creepy-toon — Creepy Toon: Creepy Toon pictures.\n- claymation — Claymation: Claymation pictures.\n- cartoon — Cartoon: Cartoon pictures.\n- fantasy-art — Fantasy Art: Fantasy Art pictures.\n- kawaii — Kawaii: Kawaii pictures.\n- cinematic — Cinematic: Cinematic pictures.\n- digital-art — Digital Art: Digital Art pictures.\n- neon-futuristic — Neon Futuristic: Neon Futuristic pictures.\n- comic-book — Comic Book: Comic Book pictures.\n- playground — Playground: Playground pictures.\n- anime — Anime: Anime pictures.\nDefault: realistic-4k.","type":"string","enum":["realistic-4k","creepy-toon","claymation","cartoon","fantasy-art","kawaii","cinematic","digital-art","neon-futuristic","comic-book","playground","anime"]},"secondsPerImage":{"description":"Cut speed: How many seconds each picture stays on screen. Faster cuts mean more pictures, which costs more. From 2 to 6 seconds. Default: 3.","type":"integer","minimum":2,"maximum":6},"scriptMode":{"description":"Writer: Which writer makes the script.\nChoices:\n- normal — Standard: A good script, quickly. (25 credits per minute of video)\n- max — Max: The strongest writer: better hooks and pacing. (50 credits per minute of video)\nDefault: normal.","type":"string","enum":["normal","max"]},"sfxMode":{"description":"Sound effects: How the sound effects are chosen.\nChoices:\n- standard — Standard: Sound effects matched to each scene.\n- premium — Premium: More, better-placed sound effects. (30 credits per minute of video)\nDefault: standard.","type":"string","enum":["standard","premium"]},"animation":{"description":"Movement: Whether pictures come alive as short video clips. Left out, a new video gets the same default as Quick Create and Ask: a short (9:16, up to 3 min) moves in every scene on AutoClips with its clips made straight from the script, and anything longer or wider stays stills. The create page opens a longer or wider video with its opening scene moving instead: send opening for that. While it is left out, it follows a new length or shape set before the pictures are made, as a new video of that length and shape gets. Every clip also pays 5 credits for planning it.\nChoices:\n- none — Stills: Pictures with gentle camera moves. No clips.\n- opening — Moving opening: The first scene is a video clip, to hook viewers. (One clip at the movement model's price, plus 5 credits to plan it)\n- every_scene — Every scene moves: Every scene is a video clip. (One clip per 5 seconds the script really runs, at the movement model's price plus 5 credits a clip to plan it)\nDefault: every scene on AutoClips for a short, else stills (leave it out).","type":"string","enum":["none","opening","every_scene"]},"animationModel":{"description":"Movement model: Which model makes the video clips (only used when Movement is not \"none\").\nChoices:\n- autoclips1 — Best value (AutoClips 1): Our own video model: natural motion, 768p, 5-second clips, every shape. Can make clips straight from the script (see directVideo). (75 credits per clip)\n- autoclips1Upscaled — Sharper (AutoClips 1 1080p Upscaled): AutoClips 1, sharpened to 1080p after it is made. Can make clips straight from the script. (102 credits per clip)\n- autoclips1Light — Cheapest (AutoClips 1 Lite): Half the price of AutoClips 1, at 720p. Can make clips straight from the script, but not from your character pictures (directVideo with consistency). (38 credits per clip)\n- autoclips1LightHd — Lite in Full HD (AutoClips 1 Lite Full HD): AutoClips 1 Lite drawn at full 1080p. Can make clips straight from the script, but not from your character pictures (directVideo with consistency). (113 credits per clip)\n- seedancePro — Steadiest characters (Seedance 1.5 Pro): The newer Seedance: steadier characters, 5-second clips. (55 credits per clip)\n- seedanceLite — Fastest (Seedance 1.0 Lite): Quick 5-second clips. (100 credits per clip)\n- kling3Video — Best movement (Kling 3.0): The newest Kling: the best motion, 5-second clips. (270 credits per clip)\n- klingVideo — Smooth movement (Kling 2.6): Strong, smooth motion, 5-second clips. (200 credits per clip)\n- grokImagineVideo — Sharpest (Grok Video): Higher quality 6-second clips. (250 credits per clip)\n- omniMax — Best overall (Pro Max): The best quality, made fastest. Only for 9:16 and 16:9; on 1:1 it is replaced by Seedance 1.0 Lite at that model's lower price. (400 credits per clip)\n- autoclipsVideo — Best value (AutoClips 1, old name): The old name of autoclips1, still taken. Send autoclips1 instead. (75 credits per clip)\nDefault: autoclips1.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd","seedancePro","seedanceLite","kling3Video","klingVideo","grokImagineVideo","omniMax","autoclipsVideo"]},"directVideo":{"description":"Clips straight from the script: Only when Movement is every_scene on an AutoClips model (autoclips1, autoclips1Upscaled, autoclips1Light, autoclips1LightHd): each clip is made straight from the script, with no picture drawn first; with consistent characters, from the character and place pictures too. No picture per clip is paid for: each clip costs its model's clip price. Without consistent characters, people and places can change between clips. With them, add up to 9 character and place pictures at 25 credits each. The Lite models cannot do this: send consistency false or directVideo false with them. Off (\"Picture first\"): a picture is drawn for each clip, then the clip. On by default, as in the app. Sent without animation, it applies to the default movement (on a short, false means picture first). Ignored (saved as off) for other movement; true is refused where it cannot apply. Default: true.","type":"boolean"},"consistency":{"description":"Keeps the same faces and places across scenes by first drawing a reference picture for each character and place that comes back. Doubles the picture price, except Krea 2: 25 credits a picture instead of 20 (not available for Z-Image Turbo or web search). If nobody and nowhere comes back, nothing is drawn and the pictures cost the plain price.","type":"boolean"},"language":{"title":"Language (AutoClips V3 (cinematic stories) option language)","description":"Language: The language of the narration, captions and title.\nOne of 94 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=v3&option=language) to see them all.\nChoices:\n- en — English: English narration and captions.\n- es — Spanish: Spanish narration and captions.\n- pt — Portuguese: Portuguese narration and captions.\n- fr — French: French narration and captions.\n- de — German: German narration and captions.\n- hi — Hindi: Hindi narration and captions.\n- ar — Arabic: Arabic narration and captions.\n- ja — Japanese: Japanese narration and captions.\n- zh — Chinese: Chinese narration and captions.\n- id — Indonesian: Indonesian narration and captions.\n- ru — Russian: Russian narration and captions.\n- tr — Turkish: Turkish narration and captions.\n- ko — Korean: Korean narration and captions.\n- it — Italian: Italian narration and captions.\n- nl — Dutch: Dutch narration and captions.\n- pl — Polish: Polish narration and captions.\n- ro — Romanian: Romanian narration and captions.\n- cs — Czech: Czech narration and captions.\n- sk — Slovak: Slovak narration and captions.\n- hu — Hungarian: Hungarian narration and captions.\n- sv — Swedish: Swedish narration and captions.\n- da — Danish: Danish narration and captions.\n- no — Norwegian: Norwegian narration and captions.\n- fi — Finnish: Finnish narration and captions.\n- is — Icelandic: Icelandic narration and captions.\n- et — Estonian: Estonian narration and captions.\n- lv — Latvian: Latvian narration and captions.\n- lt — Lithuanian: Lithuanian narration and captions.\n- el — Greek: Greek narration and captions.\n- bg — Bulgarian: Bulgarian narration and captions.\n…and 64 more.\nDefault: en.","type":"string"},"voice":{"description":"The narrator: a voice id or name from autoclips_voices (the library or your own cloned voices). Leave it out for the default narrator. With delivery characters (AI Actors) there is no narrator: each actor speaks in their own voice, and this voice is only for the first person who has none; left out, each of them gets a fitting voice.","type":"string","minLength":1,"maxLength":120},"voiceModel":{"description":"Voice model: Which voice model reads the narration. A new project starts on your account's voice model: the one you last picked in the app (shared with Character Explainer), or Eleven v4 if you never picked one. autoclips_account voice_model shows it and set_voice_model changes it. A project keeps the model it was made with.\nChoices:\n- eleven_v4 — Eleven v4: Recommended. The newest model, best for every language. Emotions written in [brackets] are acted out.\n- eleven_v3 — Eleven v3: An older model. Emotions written in [brackets] are acted out.\n- eleven_multilingual_v2 — Multilingual v2: An older model: a steady read, with no emotion tags. It cannot speak Thai, Vietnamese, Hungarian, Norwegian and Lithuanian, so those are voiced with Eleven v4. It cannot speak Georgian, so that language is voiced with Eleven v3.\nDefault: your account's voice model (leave it out).","type":"string","enum":["eleven_v4","eleven_v3","eleven_multilingual_v2"]},"captions":{"description":"Show spoken words on screen.","type":"boolean"},"motionText":{"description":"Headline and pop-up text: A bold headline over the first seconds, then pop-up text on key moments, each with a short sound. Vertical (9:16) videos only: a 16:9 or 1:1 video gets none, even with this on. On by default, as in the app. No extra credits. Default: true.","type":"boolean"},"subjectWobble":{"description":"For the Creepy Toon style: cut-out subjects gently wobble. Beta.","type":"boolean"},"hookIntro":{"description":"AI hook intro: Only for a pasted story or a Reddit post: open the video with one punchy hook line teasing the story's most shocking moment, then the story as it is written (a script without its formatting). On by default, as in the app. No extra credits. Default: true.","type":"boolean"},"cliffhanger":{"description":"End on a cliffhanger: Only for a video written from a topic: stop the story at the big reveal, so viewers want the next part. Off: the story gets a complete ending, as in the app. No extra credits. Default: false.","type":"boolean"},"delivery":{"description":"Who tells the story: narrator: a voice reads the story over the pictures, as always. characters: no narrator; realistic people say every line on camera with moving lips, each in their own voice (a voice on the character, including your own clone; pick it with v3.characters update). No narrator voice is needed: a voice sent is only for the first person with no voice of their own, and anyone without one gets a fitting voice. Topic videos in English only. Priced by the seconds filmed on speakModel.\nChoices:\n- narrator — Narrator: A voice reads the story over the pictures.\n- characters — AI Actors: No narrator: realistic people say every line on camera, each in their own voice.\nDefault: narrator.","type":"string","enum":["narrator","characters"]},"speakModel":{"description":"AI Actors: look: Only with delivery characters. seedanceMini (Realistic, 25 credits per second filmed): The best acting for the price. Faces hold from clip to clip. wan3 (Closest to your photo, 48 credits per second filmed): Natural skin and the nearest match to the picture. Calmer acting. seedance25 (Most cinematic, 85 credits per second filmed): Looks most like a real film. Softer picture, and the highest price. minimaxH3 (Lowest price, 24 credits per second filmed): Very real for one person. Can lose where people stand with three or more.\nChoices:\n- seedanceMini — Realistic: The best acting for the price. Faces hold from clip to clip.\n- wan3 — Closest to your photo: Natural skin and the nearest match to the picture. Calmer acting.\n- seedance25 — Most cinematic: Looks most like a real film. Softer picture, and the highest price.\n- minimaxH3 — Lowest price: Very real for one person. Can lose where people stand with three or more.\nDefault: seedanceMini.","type":"string","enum":["seedanceMini","wan3","seedance25","minimaxH3"]},"likenessRightsConfirmed":{"description":"I have the right to use these faces and voices: Required as true for delivery characters with your own characters: you confirm you have the right to use the face and voice of everyone you add. Default: false.","type":"boolean"},"watermarkType":{"description":"Watermark: Your text or picture on the video. Every plan.\nChoices:\n- none — None: No watermark.\n- text — Text: watermarkText.\n- image — Picture: watermarkMediaId.\nDefault: none.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"Text: The words. Default: No text (leave it out).","type":"string","minLength":1,"maxLength":50},"watermarkTextColor":{"description":"Text colour: #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundColor":{"description":"Box colour: #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundOpacity":{"description":"Box: Box, 0 (none) to 1. From 0 to 1, in steps of 0.01. Default: 0.5.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"watermarkMediaId":{"description":"A picture from autoclips_media, by id. Default: No picture (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"watermarkImageOpacity":{"description":"Picture opacity: 0.3 to 1. From 0.3 to 1, in steps of 0.01. Default: 0.7.","type":"number","minimum":0.3,"maximum":1,"multipleOf":0.01},"watermarkVerticalPosition":{"description":"Height: Percent from the top. From 10 to 90 percent. Default: 85.","type":"integer","minimum":10,"maximum":90},"watermarkHorizontalPosition":{"description":"Across: Percent from the left. From 5 to 95 percent. Default: 85.","type":"integer","minimum":5,"maximum":95},"watermarkScale":{"description":"Size: 1 is normal. From 0.5 to 3, in steps of 0.01. Default: 1.","type":"number","minimum":0.5,"maximum":3,"multipleOf":0.01},"watermarkStartSeconds":{"description":"From: Seconds into the video it appears. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"watermarkEndSeconds":{"description":"Until: Seconds into the video it goes; 0 = to the end. At least 0.5 s after the start. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"outroId":{"description":"Outro: An end card from autoclips_outros, after the last scene. Paid plans (free: plan_required). \"none\" = no outro. Default: No outro (leave it out).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"characterIds":{"description":"Up to 4 of your saved characters (ids from the V3 characters list) to star in the video (the app's Featured characters). Turns consistent characters on.","maxItems":4,"type":"array","items":{"description":"characterId","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"characterVoices":{"description":"With delivery characters (AI Actors): the voice each featured character speaks in, in this video only. A character left out speaks in the voice saved on the character, or a voice picked for them (a different one for each). Each characterId must be in characterIds.","maxItems":4,"type":"array","items":{"type":"object","properties":{"characterId":{"description":"characterId","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"voice":{"description":"A voice id or name from autoclips_voices (a library voice or your own cloned voice), or null to have a voice picked for them even when the character has its own.","anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]}},"required":["characterId","voice"],"additionalProperties":false}},"publishing":{"description":"Auto-post the finished video to your connected social accounts.","type":"object","properties":{"platforms":{"description":"Where to post the video automatically once it is rendered: any of tiktok, youtube, instagram, facebook, twitter. An empty list turns auto-posting off. Each platform needs a connected account, a monthly or annual plan that auto-posts, and a key with the publish permission.","maxItems":5,"type":"array","items":{"type":"string","enum":["tiktok","youtube","instagram","facebook","twitter"]}},"youtubePrivacy":{"description":"YouTube visibility. Default: private.","type":"string","enum":["private","unlisted","public"]},"aiDisclosure":{"description":"Label the post as AI-made where the platform supports it. Default: false.","type":"boolean"}},"required":["platforms"],"additionalProperties":false}},"additionalProperties":false},"example":{"topic":"How volcanoes form","category":"science","durationSeconds":60,"style":"cinematic"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"description":"Where the project is: draft, generating-script, script-ready, generating-assets, assets-ready, generating-edl, edl-ready, rendering, completed, failed.","type":"string"},"stage":{"description":"The status in plain words.","type":"string"},"progress":{"type":"number"},"problem":{"description":"Why it stopped, when status is failed.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"settings":{"description":"The project's settings, in the same words the create and update actions take.","type":"object","properties":{},"additionalProperties":{}},"series":{"description":"Its place in a series. To make the next part, quick_create with series.previousProjectId set to this project's id: it starts from this project's settings, as the app's \"Create Part N\" does. The step-by-step way (a new draft from create, then v3_script generate with series) carries on the story only: the draft starts from the default settings (length, shape, language, look, featured characters), not this project's, unless you send them to create.","type":"object","properties":{"part":{"description":"Which part of a series this video is (1 for a video on its own).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"previousProjectId":{"description":"The project of the part before, when this one continues it.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["part","previousProjectId"],"additionalProperties":{}},"input":{"type":"object","properties":{},"additionalProperties":{}},"counts":{"type":"object","properties":{},"additionalProperties":{}},"video":{"description":"The finished video, once rendered.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"render":{"type":"object","properties":{},"additionalProperties":{}},"pipeline":{"description":"Quick Create progress, for projects made with quick_create. stalled is true when a run reads running but its server stopped (no sign of it for 5 minutes): retry carries it on.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"revisions":{"type":"object","properties":{},"additionalProperties":{}},"credits":{"description":"Credits already paid for the script and for the pictures and voice.","type":"object","properties":{},"additionalProperties":{}},"isDemo":{"type":"boolean"},"links":{"description":"Where to open the project in the app.","type":"object","properties":{},"additionalProperties":{}}},"required":["id","product","title","status","stage","progress","problem","createdAt","updatedAt","settings","series","input","counts","video","render","pipeline","revisions","credits","isDemo","links"],"additionalProperties":{}}},"required":["project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"3f6c1a52-8d7e-4b1f-9a0c-2e5d7b9c4f10","product":"v3","title":"How volcanoes form","status":"draft","stage":"Draft: settings saved, no script yet","progress":0,"problem":null,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","settings":{"category":"science","durationSeconds":60,"aspectRatio":"9:16","imageModel":"grokImagine","style":"cinematic","secondsPerImage":3,"scriptMode":"normal","sfxMode":"standard","animation":"every_scene","animationModel":"autoclips1","directVideo":true,"consistency":false,"language":"en","voiceId":null,"voiceModel":"eleven_v4","captions":true,"motionText":true,"subjectWobble":false,"hookIntro":null,"cliffhanger":false,"watermarkType":"none","watermarkText":null,"watermarkTextColor":"#FFFFFF","watermarkBackgroundColor":"#000000","watermarkBackgroundOpacity":0.5,"watermarkImageOpacity":0.7,"watermarkVerticalPosition":85,"watermarkHorizontalPosition":85,"watermarkScale":1,"watermarkStartSeconds":0,"watermarkEndSeconds":0,"outroId":null},"series":{"part":1,"previousProjectId":null},"input":{"mode":"topic","topic":"How volcanoes form","storyTitle":null,"hasStoryText":false,"redditUrl":null},"counts":{"scenes":0,"pictures":0,"picturesReady":0},"video":null,"render":{"status":"idle","progress":0},"pipeline":null,"revisions":{"script":0,"timeline":0},"credits":{"script":0,"assets":0,"assetsLengthSeconds":null,"returnedForShorterVideo":0},"isDemo":false,"links":{"app":"https://app.autoclips.app/create/cinematic-story?project=3f6c1a52-8d7e-4b1f-9a0c-2e5d7b9c4f10","editor":"https://app.autoclips.app/editor/3f6c1a52-8d7e-4b1f-9a0c-2e5d7b9c4f10"}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/quick":{"post":{"operationId":"v3_projects_quick_create","summary":"Make a whole V3 video in one go: script, pictures, voice, music and render. Costs credits; answers with a job.","description":"Quick Create runs every step on its own and you follow a job (autoclips_jobs) until the video is ready. Same story sources and settings as create, saved characters (characterIds) and consistent characters included: it draws the characters and places before the pictures. series makes the next part of a series (a topic, or no topic to carry on where the previous part ended); like the app's \"Create Part N\", it starts from the previous part's settings (category, length, shape, look, movement, consistent characters, featured characters, language, narrator and voice model), and any setting sent wins. music picks the background music as the app's Music picker does: auto (left out), a score written for the video (ai, extra credits), none, a track from the AutoClips music library, or music you uploaded in the app that one of your V3 videos already uses. Movement left out is the same default as Ask: every scene moves on AutoClips for a short (9:16 up to 3 minutes), stills otherwise (the create page opens a longer or wider video with its opening scene moving instead: send animation opening for that). Headline and pop-up text (motionText) is on unless you send false: a bold headline over the first seconds, then pop-up text on key moments, on 9:16 videos only, at no extra cost. What you approve is a spending limit, charged in two parts while it runs: the script at its length, then the pictures, voice and music (rendering included) at the length the written script really runs, which is often a little longer. The limit is the most the run can be charged, for a script as long as the narration may be, and can be well above the expected price the notes give; over REST, max_credits must cover the limit. A pasted or Reddit story longer than the chosen length raises the length (by what is read aloud: a story written as a script is narrated without its formatting), and the quote shows that. With publishing, the finished video is posted to those accounts (the quote says so; it needs the publish permission). Sending the same request again with the same Idempotency-Key hands back the same project and job; it never starts a second one. If a try failed after its video had started, the same request sent again within 10 minutes (even with a new key or a new approval) carries on that video while it is still being made, instead of starting a second one, and says so (continued: true); once that video failed or finished, the same request makes a new one.\n\n**Permissions:** spend.\n**Cost:** You approve a spending limit, not a price: the work is charged step by step as it runs, usually less. The limit is the most V3 Quick Create can charge. Send `max_credits` (the highest spending limit you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the limit and a quote_token.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["spend"]}],"x-autoclips-operation":"v3.projects.quick_create","x-autoclips-scopes":["spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"v3_projects action=quick_create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"topic":{"description":"What the video is about, in a sentence or two. The writer turns it into a story. Send exactly one of topic, story or redditUrl.","type":"string","minLength":3,"maxLength":2000},"story":{"description":"Your own story, narrated word for word (a script without its formatting). Send exactly one of topic, story or redditUrl.","type":"object","properties":{"title":{"description":"The story's title.","type":"string","maxLength":200},"text":{"description":"The story, read out word for word (50 to 50,000 characters). A story written as a script is narrated without most of its formatting: timestamps, scene headings (\"Scene 2: …\", \"INT. …\"), camera and edit notes (\"Wide shot:\", \"Cut to:\"), sound and music note lines (\"SFX: …\") and speaker names before a colon (\"AIKO: …\") are left out, and so is an acting note in brackets such as (whispering) on its own line, after the name, or opening a line in three words or fewer (a voice model that performs audio tags may get it as a tag). Still read aloud: a name on a line of its own, a lone \"Name:\" in plain prose, and a note inside a sentence or longer than three words. Its length is what is read aloud.","type":"string","minLength":50,"maxLength":50000}},"required":["text"],"additionalProperties":false},"redditUrl":{"description":"A Reddit post to narrate word for word (any script formatting in it is not read aloud); its title and text are imported. Send exactly one of topic, story or redditUrl.","type":"string","maxLength":500,"pattern":"^https:\\/\\/(?:www\\.|old\\.|new\\.)?reddit\\.com\\/r\\/[A-Za-z0-9_]{2,40}\\/comments\\/[A-Za-z0-9]{3,20}(?:\\/[^\\s?#]*)?(?:\\?[^\\s#]*)?$"},"recipe":{"description":"Recipe: A shortcut that fills in several settings at once, like the three cards in the app. Any setting you also send wins over the recipe. Like a card in the app, a recipe is fitted to your account and video: a length above your plan's longest is cut to it, Pro Max movement on a 1:1 video is made on AutoClips instead, and with saved characters a picture maker without consistent characters is swapped for one with them. The answer's notes say what was changed.\nChoices:\n- quick — Quick: Cheapest way to see the idea work: 60 s, standard writer, stills, lowest-cost pictures.\n- standard — Standard: What most finished videos use: 60 s, max writer, every scene moves on AutoClips with its clips made straight from the script, Grok pictures, no consistent characters.\n- cinematic — Cinematic: Every scene moves: 3 min, max writer, premium sound, Pro Max clips, Seedream pictures, consistent characters.\nDefault: No recipe (leave it out).","type":"string","enum":["quick","standard","cinematic"]},"category":{"description":"Category: The kind of story. It shapes the writing, the moods, the music and the look. Use \"general\" if unsure.\nChoices:\n- horror — Horror & Dark Facts: Creepy stories, dark history, unsettling facts\n- science — Science & Nature: Scientific discoveries, natural phenomena, how things work\n- history — History & Ancient Mysteries: Ancient civilizations, historical events, mysteries from the past\n- crime — Crime & Mystery: True crime, mysteries, forensics, detective stories\n- space — Space & Cosmos: Astronomy, space exploration, cosmic mysteries\n- nature — Animals & Wildlife: Animal facts, wildlife, evolution, ecosystems\n- travel — Travel & Culture: Destinations, nightlife, cultural experiences, world exploration\n- food — Food & Cuisine: Cooking, street food, food science, culinary traditions\n- technology — Technology: AI, gadgets, future tech, digital world, cybersecurity\n- psychology — Psychology & Mind: Human behavior, mental health, cognitive biases, social experiments\n- mythology — Mythology & Legends: Gods, mythical creatures, ancient legends, folklore\n- general — General: Any topic — adapts style to your content automatically\nDefault: general.","type":"string","enum":["horror","science","history","crime","space","nature","travel","food","technology","psychology","mythology","general"]},"durationSeconds":{"description":"How long the video is meant to run. The script is written for this length and charged for it. Everything after the script is priced at the length the written script really runs, which is often a little longer or shorter: narration 60 credits a minute, rendering the finished video 30 credits a minute, and pictures, clips and sound effects by that length. Made step by step, generate_assets shows that price before it charges; Quick Create charges it within the limit you approved. A recording that runs shorter gets the difference back. Your plan sets the longest length you can pick. One of 60, 65, 75, 90, 100, 120, 180, 300, 600, 900, 1200 seconds, as a number (60) or as the options' text id (\"60\").","anyOf":[{"type":"number","enum":[60,65,75,90,100,120,180,300,600,900,1200]},{"type":"string","pattern":"^(?:60|65|75|90|100|120|180|300|600|900|1200)$"}]},"aspectRatio":{"description":"Shape: The frame of the video.\nChoices:\n- 9:16 — Tall 9:16: TikTok, Reels and Shorts.\n- 16:9 — Wide 16:9: YouTube.\n- 1:1 — Square 1:1: Instagram feed.\nDefault: 9:16.","type":"string","enum":["9:16","16:9","1:1"]},"imageModel":{"description":"Picture maker: Which model makes the pictures. It sets the look, the speed and the price per picture.\nChoices:\n- grokImagine — Fast and sharp (Grok Imagine): High quality and quick. Supports consistent characters. (20 credits per picture (doubled with consistent characters))\n- seedream5Flash — Sharp for less (Seedream 5 Flash): Sharp pictures at a low price. Supports consistent characters. (12.5 credits per picture (doubled with consistent characters))\n- zImageTurbo — Lowest cost (Z-Image Turbo): The most affordable pictures. No consistent characters. (6.25 credits per picture)\n- fluxSchnell — Best value (Flux 2 Turbo): Good quality for the price. Supports consistent characters. (12.5 credits per picture (doubled with consistent characters))\n- fluxDev — All-rounder (Flux 2): Solid quality for most topics. (18.75 credits per picture (doubled with consistent characters))\n- krea2Medium — Most artistic (Krea 2): Striking, artistic looks. (20 credits per picture (25 with consistent characters))\n- seedream45 — Best faces (Seedream 4.5): The steadiest faces and characters. Slower. (25 credits per picture (doubled with consistent characters))\n- fluxPro — Highest detail (Flux 2 Pro): The most detail per picture. (25 credits per picture (doubled with consistent characters))\n- nanoBanana2 — Follows the prompt (Nano Banana 2): Closest to what the script asks for, 2K pictures. The most expensive. (72 credits per picture (doubled with consistent characters))\n- webSearch — Real photos (web search): Real photos found on the web instead of generated pictures. No consistent characters. (6.25 credits per picture)\nDefault: grokImagine.","type":"string","enum":["grokImagine","seedream5Flash","zImageTurbo","fluxSchnell","fluxDev","krea2Medium","seedream45","fluxPro","nanoBanana2","webSearch"]},"style":{"description":"Style: The art style of every picture.\nChoices:\n- realistic-4k — 4k Realistic: 4k Realistic pictures.\n- creepy-toon — Creepy Toon: Creepy Toon pictures.\n- claymation — Claymation: Claymation pictures.\n- cartoon — Cartoon: Cartoon pictures.\n- fantasy-art — Fantasy Art: Fantasy Art pictures.\n- kawaii — Kawaii: Kawaii pictures.\n- cinematic — Cinematic: Cinematic pictures.\n- digital-art — Digital Art: Digital Art pictures.\n- neon-futuristic — Neon Futuristic: Neon Futuristic pictures.\n- comic-book — Comic Book: Comic Book pictures.\n- playground — Playground: Playground pictures.\n- anime — Anime: Anime pictures.\nDefault: realistic-4k.","type":"string","enum":["realistic-4k","creepy-toon","claymation","cartoon","fantasy-art","kawaii","cinematic","digital-art","neon-futuristic","comic-book","playground","anime"]},"secondsPerImage":{"description":"Cut speed: How many seconds each picture stays on screen. Faster cuts mean more pictures, which costs more. From 2 to 6 seconds. Default: 3.","type":"integer","minimum":2,"maximum":6},"scriptMode":{"description":"Writer: Which writer makes the script.\nChoices:\n- normal — Standard: A good script, quickly. (25 credits per minute of video)\n- max — Max: The strongest writer: better hooks and pacing. (50 credits per minute of video)\nDefault: normal.","type":"string","enum":["normal","max"]},"sfxMode":{"description":"Sound effects: How the sound effects are chosen.\nChoices:\n- standard — Standard: Sound effects matched to each scene.\n- premium — Premium: More, better-placed sound effects. (30 credits per minute of video)\nDefault: standard.","type":"string","enum":["standard","premium"]},"animation":{"description":"Movement: Whether pictures come alive as short video clips. Left out, a new video gets the same default as Quick Create and Ask: a short (9:16, up to 3 min) moves in every scene on AutoClips with its clips made straight from the script, and anything longer or wider stays stills. The create page opens a longer or wider video with its opening scene moving instead: send opening for that. While it is left out, it follows a new length or shape set before the pictures are made, as a new video of that length and shape gets. Every clip also pays 5 credits for planning it.\nChoices:\n- none — Stills: Pictures with gentle camera moves. No clips.\n- opening — Moving opening: The first scene is a video clip, to hook viewers. (One clip at the movement model's price, plus 5 credits to plan it)\n- every_scene — Every scene moves: Every scene is a video clip. (One clip per 5 seconds the script really runs, at the movement model's price plus 5 credits a clip to plan it)\nDefault: every scene on AutoClips for a short, else stills (leave it out).","type":"string","enum":["none","opening","every_scene"]},"animationModel":{"description":"Movement model: Which model makes the video clips (only used when Movement is not \"none\").\nChoices:\n- autoclips1 — Best value (AutoClips 1): Our own video model: natural motion, 768p, 5-second clips, every shape. Can make clips straight from the script (see directVideo). (75 credits per clip)\n- autoclips1Upscaled — Sharper (AutoClips 1 1080p Upscaled): AutoClips 1, sharpened to 1080p after it is made. Can make clips straight from the script. (102 credits per clip)\n- autoclips1Light — Cheapest (AutoClips 1 Lite): Half the price of AutoClips 1, at 720p. Can make clips straight from the script, but not from your character pictures (directVideo with consistency). (38 credits per clip)\n- autoclips1LightHd — Lite in Full HD (AutoClips 1 Lite Full HD): AutoClips 1 Lite drawn at full 1080p. Can make clips straight from the script, but not from your character pictures (directVideo with consistency). (113 credits per clip)\n- seedancePro — Steadiest characters (Seedance 1.5 Pro): The newer Seedance: steadier characters, 5-second clips. (55 credits per clip)\n- seedanceLite — Fastest (Seedance 1.0 Lite): Quick 5-second clips. (100 credits per clip)\n- kling3Video — Best movement (Kling 3.0): The newest Kling: the best motion, 5-second clips. (270 credits per clip)\n- klingVideo — Smooth movement (Kling 2.6): Strong, smooth motion, 5-second clips. (200 credits per clip)\n- grokImagineVideo — Sharpest (Grok Video): Higher quality 6-second clips. (250 credits per clip)\n- omniMax — Best overall (Pro Max): The best quality, made fastest. Only for 9:16 and 16:9; on 1:1 it is replaced by Seedance 1.0 Lite at that model's lower price. (400 credits per clip)\n- autoclipsVideo — Best value (AutoClips 1, old name): The old name of autoclips1, still taken. Send autoclips1 instead. (75 credits per clip)\nDefault: autoclips1.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd","seedancePro","seedanceLite","kling3Video","klingVideo","grokImagineVideo","omniMax","autoclipsVideo"]},"directVideo":{"description":"Clips straight from the script: Only when Movement is every_scene on an AutoClips model (autoclips1, autoclips1Upscaled, autoclips1Light, autoclips1LightHd): each clip is made straight from the script, with no picture drawn first; with consistent characters, from the character and place pictures too. No picture per clip is paid for: each clip costs its model's clip price. Without consistent characters, people and places can change between clips. With them, add up to 9 character and place pictures at 25 credits each. The Lite models cannot do this: send consistency false or directVideo false with them. Off (\"Picture first\"): a picture is drawn for each clip, then the clip. On by default, as in the app. Sent without animation, it applies to the default movement (on a short, false means picture first). Ignored (saved as off) for other movement; true is refused where it cannot apply. Default: true.","type":"boolean"},"consistency":{"description":"Keeps the same faces and places across scenes by first drawing a reference picture for each character and place that comes back. Doubles the picture price, except Krea 2: 25 credits a picture instead of 20 (not available for Z-Image Turbo or web search). If nobody and nowhere comes back, nothing is drawn and the pictures cost the plain price.","type":"boolean"},"language":{"title":"Language (AutoClips V3 (cinematic stories) option language)","description":"Language: The language of the narration, captions and title.\nOne of 94 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=v3&option=language) to see them all.\nChoices:\n- en — English: English narration and captions.\n- es — Spanish: Spanish narration and captions.\n- pt — Portuguese: Portuguese narration and captions.\n- fr — French: French narration and captions.\n- de — German: German narration and captions.\n- hi — Hindi: Hindi narration and captions.\n- ar — Arabic: Arabic narration and captions.\n- ja — Japanese: Japanese narration and captions.\n- zh — Chinese: Chinese narration and captions.\n- id — Indonesian: Indonesian narration and captions.\n- ru — Russian: Russian narration and captions.\n- tr — Turkish: Turkish narration and captions.\n- ko — Korean: Korean narration and captions.\n- it — Italian: Italian narration and captions.\n- nl — Dutch: Dutch narration and captions.\n- pl — Polish: Polish narration and captions.\n- ro — Romanian: Romanian narration and captions.\n- cs — Czech: Czech narration and captions.\n- sk — Slovak: Slovak narration and captions.\n- hu — Hungarian: Hungarian narration and captions.\n- sv — Swedish: Swedish narration and captions.\n- da — Danish: Danish narration and captions.\n- no — Norwegian: Norwegian narration and captions.\n- fi — Finnish: Finnish narration and captions.\n- is — Icelandic: Icelandic narration and captions.\n- et — Estonian: Estonian narration and captions.\n- lv — Latvian: Latvian narration and captions.\n- lt — Lithuanian: Lithuanian narration and captions.\n- el — Greek: Greek narration and captions.\n- bg — Bulgarian: Bulgarian narration and captions.\n…and 64 more.\nDefault: en.","type":"string"},"voice":{"description":"The narrator: a voice id or name from autoclips_voices (the library or your own cloned voices). Leave it out for the default narrator. With delivery characters (AI Actors) there is no narrator: each actor speaks in their own voice, and this voice is only for the first person who has none; left out, each of them gets a fitting voice.","type":"string","minLength":1,"maxLength":120},"voiceModel":{"description":"Voice model: Which voice model reads the narration. A new project starts on your account's voice model: the one you last picked in the app (shared with Character Explainer), or Eleven v4 if you never picked one. autoclips_account voice_model shows it and set_voice_model changes it. A project keeps the model it was made with.\nChoices:\n- eleven_v4 — Eleven v4: Recommended. The newest model, best for every language. Emotions written in [brackets] are acted out.\n- eleven_v3 — Eleven v3: An older model. Emotions written in [brackets] are acted out.\n- eleven_multilingual_v2 — Multilingual v2: An older model: a steady read, with no emotion tags. It cannot speak Thai, Vietnamese, Hungarian, Norwegian and Lithuanian, so those are voiced with Eleven v4. It cannot speak Georgian, so that language is voiced with Eleven v3.\nDefault: your account's voice model (leave it out).","type":"string","enum":["eleven_v4","eleven_v3","eleven_multilingual_v2"]},"captions":{"description":"Show spoken words on screen.","type":"boolean"},"motionText":{"description":"Headline and pop-up text: A bold headline over the first seconds, then pop-up text on key moments, each with a short sound. Vertical (9:16) videos only: a 16:9 or 1:1 video gets none, even with this on. On by default, as in the app. No extra credits. Default: true.","type":"boolean"},"subjectWobble":{"description":"For the Creepy Toon style: cut-out subjects gently wobble. Beta.","type":"boolean"},"hookIntro":{"description":"AI hook intro: Only for a pasted story or a Reddit post: open the video with one punchy hook line teasing the story's most shocking moment, then the story as it is written (a script without its formatting). On by default, as in the app. No extra credits. Default: true.","type":"boolean"},"cliffhanger":{"description":"End on a cliffhanger: Only for a video written from a topic: stop the story at the big reveal, so viewers want the next part. Off: the story gets a complete ending, as in the app. No extra credits. Default: false.","type":"boolean"},"delivery":{"description":"Who tells the story: narrator: a voice reads the story over the pictures, as always. characters: no narrator; realistic people say every line on camera with moving lips, each in their own voice (a voice on the character, including your own clone; pick it with v3.characters update). No narrator voice is needed: a voice sent is only for the first person with no voice of their own, and anyone without one gets a fitting voice. Topic videos in English only. Priced by the seconds filmed on speakModel.\nChoices:\n- narrator — Narrator: A voice reads the story over the pictures.\n- characters — AI Actors: No narrator: realistic people say every line on camera, each in their own voice.\nDefault: narrator.","type":"string","enum":["narrator","characters"]},"speakModel":{"description":"AI Actors: look: Only with delivery characters. seedanceMini (Realistic, 25 credits per second filmed): The best acting for the price. Faces hold from clip to clip. wan3 (Closest to your photo, 48 credits per second filmed): Natural skin and the nearest match to the picture. Calmer acting. seedance25 (Most cinematic, 85 credits per second filmed): Looks most like a real film. Softer picture, and the highest price. minimaxH3 (Lowest price, 24 credits per second filmed): Very real for one person. Can lose where people stand with three or more.\nChoices:\n- seedanceMini — Realistic: The best acting for the price. Faces hold from clip to clip.\n- wan3 — Closest to your photo: Natural skin and the nearest match to the picture. Calmer acting.\n- seedance25 — Most cinematic: Looks most like a real film. Softer picture, and the highest price.\n- minimaxH3 — Lowest price: Very real for one person. Can lose where people stand with three or more.\nDefault: seedanceMini.","type":"string","enum":["seedanceMini","wan3","seedance25","minimaxH3"]},"likenessRightsConfirmed":{"description":"I have the right to use these faces and voices: Required as true for delivery characters with your own characters: you confirm you have the right to use the face and voice of everyone you add. Default: false.","type":"boolean"},"watermarkType":{"description":"Watermark: Your text or picture on the video. Every plan.\nChoices:\n- none — None: No watermark.\n- text — Text: watermarkText.\n- image — Picture: watermarkMediaId.\nDefault: none.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"Text: The words. Default: No text (leave it out).","type":"string","minLength":1,"maxLength":50},"watermarkTextColor":{"description":"Text colour: #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundColor":{"description":"Box colour: #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundOpacity":{"description":"Box: Box, 0 (none) to 1. From 0 to 1, in steps of 0.01. Default: 0.5.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"watermarkMediaId":{"description":"A picture from autoclips_media, by id. Default: No picture (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"watermarkImageOpacity":{"description":"Picture opacity: 0.3 to 1. From 0.3 to 1, in steps of 0.01. Default: 0.7.","type":"number","minimum":0.3,"maximum":1,"multipleOf":0.01},"watermarkVerticalPosition":{"description":"Height: Percent from the top. From 10 to 90 percent. Default: 85.","type":"integer","minimum":10,"maximum":90},"watermarkHorizontalPosition":{"description":"Across: Percent from the left. From 5 to 95 percent. Default: 85.","type":"integer","minimum":5,"maximum":95},"watermarkScale":{"description":"Size: 1 is normal. From 0.5 to 3, in steps of 0.01. Default: 1.","type":"number","minimum":0.5,"maximum":3,"multipleOf":0.01},"watermarkStartSeconds":{"description":"From: Seconds into the video it appears. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"watermarkEndSeconds":{"description":"Until: Seconds into the video it goes; 0 = to the end. At least 0.5 s after the start. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"outroId":{"description":"Outro: An end card from autoclips_outros, after the last scene. Paid plans (free: plan_required). \"none\" = no outro. Default: No outro (leave it out).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"characterIds":{"description":"Up to 4 of your saved characters (ids from the V3 characters list) to star in the video (the app's Featured characters). Turns consistent characters on.","maxItems":4,"type":"array","items":{"description":"characterId","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"characterVoices":{"description":"With delivery characters (AI Actors): the voice each featured character speaks in, in this video only. A character left out speaks in the voice saved on the character, or a voice picked for them (a different one for each). Each characterId must be in characterIds.","maxItems":4,"type":"array","items":{"type":"object","properties":{"characterId":{"description":"characterId","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"voice":{"description":"A voice id or name from autoclips_voices (a library voice or your own cloned voice), or null to have a voice picked for them even when the character has its own.","anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]}},"required":["characterId","voice"],"additionalProperties":false}},"series":{"description":"Make the next part of a series (a video written from a topic): the writer gets the whole previous part and its characters, places and objects, and with consistent characters on, its character and place pictures are reused for free. Leave the topic out to carry on where the previous part ended, as the app does. Like the app's \"Create Part N\", the new part starts from the previous part's settings: its kind of story, length, shape, picture maker, style, cut speed, writer, sound effects, movement, consistent characters, language, narrator, voice model, ending, headline and pop-up text, and featured characters. Any setting you send wins (characterIds [] leaves the featured characters out). Captions, music and auto-posting are not carried over.","type":"object","properties":{"previousProjectId":{"description":"The V3 project of the part before this one. It must be yours and have a script.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"part":{"description":"Which part this is (2 to 20). Leave it out for the part after the previous one, as the app's \"Create Part N\" button does.","type":"integer","minimum":2,"maximum":20}},"required":["previousProjectId"],"additionalProperties":false},"music":{"description":"Background music, as the app's Music picker offers it. Leave it out for auto: a track from the AutoClips music library picked to fit the story. { \"mode\": \"none\" } has no music; { \"mode\": \"library\", \"trackId\": \"…\" } plays that library track (autoclips_timeline music lists the ids; its popular songs are not in this library); { \"mode\": \"upload\", \"musicId\": \"…\" } plays music you uploaded in the app that one of your V3 videos already uses (send mode \"upload\" alone to get their ids). { \"mode\": \"ai\" } composes a score for this video, the only choice that costs extra credits.","type":"object","properties":{"mode":{"description":"auto: we pick a track that fits the story. ai: a new score written for this video (36 credits; if it cannot be made, they come back and a library track plays). none: no music. library: the track you name with trackId. upload: music you uploaded in the app, named with musicId.","type":"string","enum":["auto","ai","none","library","upload"]},"trackId":{"description":"Only with mode \"library\": the id of a track in the AutoClips music library (for example \"horror-dark-facts-04-creeping-dread-v1\"). An unknown id is refused with suggestions.","type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9_.-]+$"},"musicId":{"description":"Only with mode \"upload\": the id of music you uploaded in the app (its My Music tab) that one of your V3 videos already uses. Uploads are kept per browser, not per account, so that is how the API knows the music is yours. Send mode \"upload\" without musicId to get the ones you can pick (candidates).","type":"string","minLength":1,"maxLength":80,"pattern":"^[A-Za-z0-9-]+$"}},"required":["mode"],"additionalProperties":false},"publishing":{"description":"Auto-post the finished video to your connected social accounts.","type":"object","properties":{"platforms":{"description":"Where to post the video automatically once it is rendered: any of tiktok, youtube, instagram, facebook, twitter. An empty list turns auto-posting off. Each platform needs a connected account, a monthly or annual plan that auto-posts, and a key with the publish permission.","maxItems":5,"type":"array","items":{"type":"string","enum":["tiktok","youtube","instagram","facebook","twitter"]}},"youtubePrivacy":{"description":"YouTube visibility. Default: private.","type":"string","enum":["private","unlisted","public"]},"aiDisclosure":{"description":"Label the post as AI-made where the platform supports it. Default: false.","type":"boolean"}},"required":["platforms"],"additionalProperties":false},"max_credits":{"type":"integer","minimum":0,"description":"The highest spending limit you accept. If the limit is higher, nothing runs and you get 402 with the limit. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run with exactly that spending limit. Works once, for 10 minutes."}},"additionalProperties":false},"example":{"topic":"The lighthouse keeper who vanished in 1900","category":"mythology","recipe":"quick"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"project":{"type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"description":"Where the project is: draft, generating-script, script-ready, generating-assets, assets-ready, generating-edl, edl-ready, rendering, completed, failed.","type":"string"},"stage":{"description":"The status in plain words.","type":"string"},"progress":{"type":"number"},"problem":{"description":"Why it stopped, when status is failed.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"settings":{"description":"The project's settings, in the same words the create and update actions take.","type":"object","properties":{},"additionalProperties":{}},"series":{"description":"Its place in a series. To make the next part, quick_create with series.previousProjectId set to this project's id: it starts from this project's settings, as the app's \"Create Part N\" does. The step-by-step way (a new draft from create, then v3_script generate with series) carries on the story only: the draft starts from the default settings (length, shape, language, look, featured characters), not this project's, unless you send them to create.","type":"object","properties":{"part":{"description":"Which part of a series this video is (1 for a video on its own).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"previousProjectId":{"description":"The project of the part before, when this one continues it.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["part","previousProjectId"],"additionalProperties":{}},"input":{"type":"object","properties":{},"additionalProperties":{}},"counts":{"type":"object","properties":{},"additionalProperties":{}},"video":{"description":"The finished video, once rendered.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"render":{"type":"object","properties":{},"additionalProperties":{}},"pipeline":{"description":"Quick Create progress, for projects made with quick_create. stalled is true when a run reads running but its server stopped (no sign of it for 5 minutes): retry carries it on.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"revisions":{"type":"object","properties":{},"additionalProperties":{}},"credits":{"description":"Credits already paid for the script and for the pictures and voice.","type":"object","properties":{},"additionalProperties":{}},"isDemo":{"type":"boolean"},"links":{"description":"Where to open the project in the app.","type":"object","properties":{},"additionalProperties":{}}},"required":["id","product","title","status","stage","progress","problem","createdAt","updatedAt","settings","series","input","counts","video","render","pipeline","revisions","credits","isDemo","links"],"additionalProperties":{}},"continued":{"description":"True when this call carried on a Quick Create that an earlier try of the same request already started (that try failed after the start, so its answer was lost). Nothing new was started: the job is that run's.","type":"boolean"}},"required":["job","project","continued"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}":{"get":{"operationId":"v3_projects_get","summary":"One V3 project: status, settings, video link, and on request its script, cast, pictures, SEO and posting.","description":"Opens one of your V3 projects. Add include to see more: script, cast, assets, seo, publishing (for example include=script,assets). Without include you get the status, settings, counts, the video link when it is ready, and links to open it in the app.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"v3.projects.get","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_projects action=get","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project id (from list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project id (from list or create).","example":"3f6c1a52-8d7e-4b1f-9a0c-2e5d7b9c4f10"},{"name":"include","in":"query","required":false,"schema":{"description":"Extra sections: script, cast, assets, seo, publishing. script = every scene's words, mood and shot; cast = consistent characters and places; assets = pictures, narration, music and clips; seo = title, description and tags; publishing = auto-posting settings and results.","maxItems":5,"type":"array","items":{"type":"string","enum":["script","cast","assets","seo","publishing"]}},"description":"Extra sections: script, cast, assets, seo, publishing. script = every scene's words, mood and shot; cast = consistent characters and places; assets = pictures, narration, music and clips; seo = title, description and tags; publishing = auto-posting settings and results.","example":["script"]}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"description":"Where the project is: draft, generating-script, script-ready, generating-assets, assets-ready, generating-edl, edl-ready, rendering, completed, failed.","type":"string"},"stage":{"description":"The status in plain words.","type":"string"},"progress":{"type":"number"},"problem":{"description":"Why it stopped, when status is failed.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"settings":{"description":"The project's settings, in the same words the create and update actions take.","type":"object","properties":{},"additionalProperties":{}},"series":{"description":"Its place in a series. To make the next part, quick_create with series.previousProjectId set to this project's id: it starts from this project's settings, as the app's \"Create Part N\" does. The step-by-step way (a new draft from create, then v3_script generate with series) carries on the story only: the draft starts from the default settings (length, shape, language, look, featured characters), not this project's, unless you send them to create.","type":"object","properties":{"part":{"description":"Which part of a series this video is (1 for a video on its own).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"previousProjectId":{"description":"The project of the part before, when this one continues it.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["part","previousProjectId"],"additionalProperties":{}},"input":{"type":"object","properties":{},"additionalProperties":{}},"counts":{"type":"object","properties":{},"additionalProperties":{}},"video":{"description":"The finished video, once rendered.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"render":{"type":"object","properties":{},"additionalProperties":{}},"pipeline":{"description":"Quick Create progress, for projects made with quick_create. stalled is true when a run reads running but its server stopped (no sign of it for 5 minutes): retry carries it on.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"revisions":{"type":"object","properties":{},"additionalProperties":{}},"credits":{"description":"Credits already paid for the script and for the pictures and voice.","type":"object","properties":{},"additionalProperties":{}},"isDemo":{"type":"boolean"},"links":{"description":"Where to open the project in the app.","type":"object","properties":{},"additionalProperties":{}}},"required":["id","product","title","status","stage","progress","problem","createdAt","updatedAt","settings","series","input","counts","video","render","pipeline","revisions","credits","isDemo","links"],"additionalProperties":{}}},"required":["project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"v3_projects_update","summary":"Change a V3 project's settings or auto-posting. What can change depends on how far the project got.","description":"Changes only the settings you send (same words as create; a recipe fills several at once). Free.\nA setting can change until the step that uses it has run:\n- before the script: everything (a new durationSeconds or aspectRatio also sets the narration speed and caption look a new video of that length and shape gets: a brisker read and pop captions for a short);\n- movement you never picked (animation left out at create and since) follows a new durationSeconds or aspectRatio the same way: every scene moves on AutoClips for a short, stills for anything longer or wider; the answer's notes say so. Sending animation picks it, and from then on it stays as you set it;\n- once the script exists (or was paid for): not category, durationSeconds, scriptMode, language, voiceModel, hookIntro or cliffhanger (the script was written with them);\n- once pictures and voice were started or paid for: not aspectRatio, imageModel, style, secondsPerImage, sfxMode, animation, animationModel, directVideo, consistency or subjectWobble;\n- hookIntro only for a story (pasted text or a Reddit post), cliffhanger only for a topic; directVideo is worked out again whenever animation or animationModel change (on for every scene on AutoClips unless you turned it off);\n- voice: until the narration is recorded;\n- captions: until the edit (timeline) is built, then switch them in the timeline editor;\n- motionText (headline and pop-up text, 9:16 only): until the edit (timeline) is built;\n- publishing (auto-posting): any time; it applies when a render finishes. Switching it on needs the publish permission, and AI apps ask the user first.\n- your watermark (watermarkType and the other watermark fields; only the ones you send change) and your outro (outroId, paid plans; \"none\" takes it off): any time, Quick Create included. They are added when the video is rendered, so a video already made shows them after you render it again (v3_production render).\nWhile Quick Create is running only captions, motionText, publishing, the watermark and the outro can change; while a cast is being built, consistency, imageModel, style and aspectRatio wait for it. A Quick Create project made without consistent characters cannot switch them on. A refused setting comes back as 409 with the reason.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.projects.update","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_projects action=update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"recipe":{"description":"Recipe: A shortcut that fills in several settings at once, like the three cards in the app. Any setting you also send wins over the recipe. Like a card in the app, a recipe is fitted to your account and video: a length above your plan's longest is cut to it, Pro Max movement on a 1:1 video is made on AutoClips instead, and with saved characters a picture maker without consistent characters is swapped for one with them. The answer's notes say what was changed.\nChoices:\n- quick — Quick: Cheapest way to see the idea work: 60 s, standard writer, stills, lowest-cost pictures.\n- standard — Standard: What most finished videos use: 60 s, max writer, every scene moves on AutoClips with its clips made straight from the script, Grok pictures, no consistent characters.\n- cinematic — Cinematic: Every scene moves: 3 min, max writer, premium sound, Pro Max clips, Seedream pictures, consistent characters.\nDefault: No recipe (leave it out).","type":"string","enum":["quick","standard","cinematic"]},"category":{"description":"Category: The kind of story. It shapes the writing, the moods, the music and the look. Use \"general\" if unsure.\nChoices:\n- horror — Horror & Dark Facts: Creepy stories, dark history, unsettling facts\n- science — Science & Nature: Scientific discoveries, natural phenomena, how things work\n- history — History & Ancient Mysteries: Ancient civilizations, historical events, mysteries from the past\n- crime — Crime & Mystery: True crime, mysteries, forensics, detective stories\n- space — Space & Cosmos: Astronomy, space exploration, cosmic mysteries\n- nature — Animals & Wildlife: Animal facts, wildlife, evolution, ecosystems\n- travel — Travel & Culture: Destinations, nightlife, cultural experiences, world exploration\n- food — Food & Cuisine: Cooking, street food, food science, culinary traditions\n- technology — Technology: AI, gadgets, future tech, digital world, cybersecurity\n- psychology — Psychology & Mind: Human behavior, mental health, cognitive biases, social experiments\n- mythology — Mythology & Legends: Gods, mythical creatures, ancient legends, folklore\n- general — General: Any topic — adapts style to your content automatically\nDefault: general.","type":"string","enum":["horror","science","history","crime","space","nature","travel","food","technology","psychology","mythology","general"]},"durationSeconds":{"description":"How long the video is meant to run. The script is written for this length and charged for it. Everything after the script is priced at the length the written script really runs, which is often a little longer or shorter: narration 60 credits a minute, rendering the finished video 30 credits a minute, and pictures, clips and sound effects by that length. Made step by step, generate_assets shows that price before it charges; Quick Create charges it within the limit you approved. A recording that runs shorter gets the difference back. Your plan sets the longest length you can pick. One of 60, 65, 75, 90, 100, 120, 180, 300, 600, 900, 1200 seconds, as a number (60) or as the options' text id (\"60\").","anyOf":[{"type":"number","enum":[60,65,75,90,100,120,180,300,600,900,1200]},{"type":"string","pattern":"^(?:60|65|75|90|100|120|180|300|600|900|1200)$"}]},"aspectRatio":{"description":"Shape: The frame of the video.\nChoices:\n- 9:16 — Tall 9:16: TikTok, Reels and Shorts.\n- 16:9 — Wide 16:9: YouTube.\n- 1:1 — Square 1:1: Instagram feed.\nDefault: 9:16.","type":"string","enum":["9:16","16:9","1:1"]},"imageModel":{"description":"Picture maker: Which model makes the pictures. It sets the look, the speed and the price per picture.\nChoices:\n- grokImagine — Fast and sharp (Grok Imagine): High quality and quick. Supports consistent characters. (20 credits per picture (doubled with consistent characters))\n- seedream5Flash — Sharp for less (Seedream 5 Flash): Sharp pictures at a low price. Supports consistent characters. (12.5 credits per picture (doubled with consistent characters))\n- zImageTurbo — Lowest cost (Z-Image Turbo): The most affordable pictures. No consistent characters. (6.25 credits per picture)\n- fluxSchnell — Best value (Flux 2 Turbo): Good quality for the price. Supports consistent characters. (12.5 credits per picture (doubled with consistent characters))\n- fluxDev — All-rounder (Flux 2): Solid quality for most topics. (18.75 credits per picture (doubled with consistent characters))\n- krea2Medium — Most artistic (Krea 2): Striking, artistic looks. (20 credits per picture (25 with consistent characters))\n- seedream45 — Best faces (Seedream 4.5): The steadiest faces and characters. Slower. (25 credits per picture (doubled with consistent characters))\n- fluxPro — Highest detail (Flux 2 Pro): The most detail per picture. (25 credits per picture (doubled with consistent characters))\n- nanoBanana2 — Follows the prompt (Nano Banana 2): Closest to what the script asks for, 2K pictures. The most expensive. (72 credits per picture (doubled with consistent characters))\n- webSearch — Real photos (web search): Real photos found on the web instead of generated pictures. No consistent characters. (6.25 credits per picture)\nDefault: grokImagine.","type":"string","enum":["grokImagine","seedream5Flash","zImageTurbo","fluxSchnell","fluxDev","krea2Medium","seedream45","fluxPro","nanoBanana2","webSearch"]},"style":{"description":"Style: The art style of every picture.\nChoices:\n- realistic-4k — 4k Realistic: 4k Realistic pictures.\n- creepy-toon — Creepy Toon: Creepy Toon pictures.\n- claymation — Claymation: Claymation pictures.\n- cartoon — Cartoon: Cartoon pictures.\n- fantasy-art — Fantasy Art: Fantasy Art pictures.\n- kawaii — Kawaii: Kawaii pictures.\n- cinematic — Cinematic: Cinematic pictures.\n- digital-art — Digital Art: Digital Art pictures.\n- neon-futuristic — Neon Futuristic: Neon Futuristic pictures.\n- comic-book — Comic Book: Comic Book pictures.\n- playground — Playground: Playground pictures.\n- anime — Anime: Anime pictures.\nDefault: realistic-4k.","type":"string","enum":["realistic-4k","creepy-toon","claymation","cartoon","fantasy-art","kawaii","cinematic","digital-art","neon-futuristic","comic-book","playground","anime"]},"secondsPerImage":{"description":"Cut speed: How many seconds each picture stays on screen. Faster cuts mean more pictures, which costs more. From 2 to 6 seconds. Default: 3.","type":"integer","minimum":2,"maximum":6},"scriptMode":{"description":"Writer: Which writer makes the script.\nChoices:\n- normal — Standard: A good script, quickly. (25 credits per minute of video)\n- max — Max: The strongest writer: better hooks and pacing. (50 credits per minute of video)\nDefault: normal.","type":"string","enum":["normal","max"]},"sfxMode":{"description":"Sound effects: How the sound effects are chosen.\nChoices:\n- standard — Standard: Sound effects matched to each scene.\n- premium — Premium: More, better-placed sound effects. (30 credits per minute of video)\nDefault: standard.","type":"string","enum":["standard","premium"]},"animation":{"description":"Movement: Whether pictures come alive as short video clips. Left out, a new video gets the same default as Quick Create and Ask: a short (9:16, up to 3 min) moves in every scene on AutoClips with its clips made straight from the script, and anything longer or wider stays stills. The create page opens a longer or wider video with its opening scene moving instead: send opening for that. While it is left out, it follows a new length or shape set before the pictures are made, as a new video of that length and shape gets. Every clip also pays 5 credits for planning it.\nChoices:\n- none — Stills: Pictures with gentle camera moves. No clips.\n- opening — Moving opening: The first scene is a video clip, to hook viewers. (One clip at the movement model's price, plus 5 credits to plan it)\n- every_scene — Every scene moves: Every scene is a video clip. (One clip per 5 seconds the script really runs, at the movement model's price plus 5 credits a clip to plan it)\nDefault: every scene on AutoClips for a short, else stills (leave it out).","type":"string","enum":["none","opening","every_scene"]},"animationModel":{"description":"Movement model: Which model makes the video clips (only used when Movement is not \"none\").\nChoices:\n- autoclips1 — Best value (AutoClips 1): Our own video model: natural motion, 768p, 5-second clips, every shape. Can make clips straight from the script (see directVideo). (75 credits per clip)\n- autoclips1Upscaled — Sharper (AutoClips 1 1080p Upscaled): AutoClips 1, sharpened to 1080p after it is made. Can make clips straight from the script. (102 credits per clip)\n- autoclips1Light — Cheapest (AutoClips 1 Lite): Half the price of AutoClips 1, at 720p. Can make clips straight from the script, but not from your character pictures (directVideo with consistency). (38 credits per clip)\n- autoclips1LightHd — Lite in Full HD (AutoClips 1 Lite Full HD): AutoClips 1 Lite drawn at full 1080p. Can make clips straight from the script, but not from your character pictures (directVideo with consistency). (113 credits per clip)\n- seedancePro — Steadiest characters (Seedance 1.5 Pro): The newer Seedance: steadier characters, 5-second clips. (55 credits per clip)\n- seedanceLite — Fastest (Seedance 1.0 Lite): Quick 5-second clips. (100 credits per clip)\n- kling3Video — Best movement (Kling 3.0): The newest Kling: the best motion, 5-second clips. (270 credits per clip)\n- klingVideo — Smooth movement (Kling 2.6): Strong, smooth motion, 5-second clips. (200 credits per clip)\n- grokImagineVideo — Sharpest (Grok Video): Higher quality 6-second clips. (250 credits per clip)\n- omniMax — Best overall (Pro Max): The best quality, made fastest. Only for 9:16 and 16:9; on 1:1 it is replaced by Seedance 1.0 Lite at that model's lower price. (400 credits per clip)\n- autoclipsVideo — Best value (AutoClips 1, old name): The old name of autoclips1, still taken. Send autoclips1 instead. (75 credits per clip)\nDefault: autoclips1.","type":"string","enum":["autoclips1","autoclips1Upscaled","autoclips1Light","autoclips1LightHd","seedancePro","seedanceLite","kling3Video","klingVideo","grokImagineVideo","omniMax","autoclipsVideo"]},"directVideo":{"description":"Clips straight from the script: Only when Movement is every_scene on an AutoClips model (autoclips1, autoclips1Upscaled, autoclips1Light, autoclips1LightHd): each clip is made straight from the script, with no picture drawn first; with consistent characters, from the character and place pictures too. No picture per clip is paid for: each clip costs its model's clip price. Without consistent characters, people and places can change between clips. With them, add up to 9 character and place pictures at 25 credits each. The Lite models cannot do this: send consistency false or directVideo false with them. Off (\"Picture first\"): a picture is drawn for each clip, then the clip. On by default, as in the app. Sent without animation, it applies to the default movement (on a short, false means picture first). Ignored (saved as off) for other movement; true is refused where it cannot apply. Default: true.","type":"boolean"},"consistency":{"description":"Keeps the same faces and places across scenes by first drawing a reference picture for each character and place that comes back. Doubles the picture price, except Krea 2: 25 credits a picture instead of 20 (not available for Z-Image Turbo or web search). If nobody and nowhere comes back, nothing is drawn and the pictures cost the plain price.","type":"boolean"},"language":{"title":"Language (AutoClips V3 (cinematic stories) option language)","description":"Language: The language of the narration, captions and title.\nOne of 94 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=v3&option=language) to see them all.\nChoices:\n- en — English: English narration and captions.\n- es — Spanish: Spanish narration and captions.\n- pt — Portuguese: Portuguese narration and captions.\n- fr — French: French narration and captions.\n- de — German: German narration and captions.\n- hi — Hindi: Hindi narration and captions.\n- ar — Arabic: Arabic narration and captions.\n- ja — Japanese: Japanese narration and captions.\n- zh — Chinese: Chinese narration and captions.\n- id — Indonesian: Indonesian narration and captions.\n- ru — Russian: Russian narration and captions.\n- tr — Turkish: Turkish narration and captions.\n- ko — Korean: Korean narration and captions.\n- it — Italian: Italian narration and captions.\n- nl — Dutch: Dutch narration and captions.\n- pl — Polish: Polish narration and captions.\n- ro — Romanian: Romanian narration and captions.\n- cs — Czech: Czech narration and captions.\n- sk — Slovak: Slovak narration and captions.\n- hu — Hungarian: Hungarian narration and captions.\n- sv — Swedish: Swedish narration and captions.\n- da — Danish: Danish narration and captions.\n- no — Norwegian: Norwegian narration and captions.\n- fi — Finnish: Finnish narration and captions.\n- is — Icelandic: Icelandic narration and captions.\n- et — Estonian: Estonian narration and captions.\n- lv — Latvian: Latvian narration and captions.\n- lt — Lithuanian: Lithuanian narration and captions.\n- el — Greek: Greek narration and captions.\n- bg — Bulgarian: Bulgarian narration and captions.\n…and 64 more.\nDefault: en.","type":"string"},"voice":{"description":"The narrator: a voice id or name from autoclips_voices (the library or your own cloned voices). Leave it out for the default narrator. With delivery characters (AI Actors) there is no narrator: each actor speaks in their own voice, and this voice is only for the first person who has none; left out, each of them gets a fitting voice.","type":"string","minLength":1,"maxLength":120},"voiceModel":{"description":"Voice model: Which voice model reads the narration. A new project starts on your account's voice model: the one you last picked in the app (shared with Character Explainer), or Eleven v4 if you never picked one. autoclips_account voice_model shows it and set_voice_model changes it. A project keeps the model it was made with.\nChoices:\n- eleven_v4 — Eleven v4: Recommended. The newest model, best for every language. Emotions written in [brackets] are acted out.\n- eleven_v3 — Eleven v3: An older model. Emotions written in [brackets] are acted out.\n- eleven_multilingual_v2 — Multilingual v2: An older model: a steady read, with no emotion tags. It cannot speak Thai, Vietnamese, Hungarian, Norwegian and Lithuanian, so those are voiced with Eleven v4. It cannot speak Georgian, so that language is voiced with Eleven v3.\nDefault: your account's voice model (leave it out).","type":"string","enum":["eleven_v4","eleven_v3","eleven_multilingual_v2"]},"captions":{"description":"Show spoken words on screen.","type":"boolean"},"motionText":{"description":"Headline and pop-up text: A bold headline over the first seconds, then pop-up text on key moments, each with a short sound. Vertical (9:16) videos only: a 16:9 or 1:1 video gets none, even with this on. On by default, as in the app. No extra credits. Default: true.","type":"boolean"},"subjectWobble":{"description":"For the Creepy Toon style: cut-out subjects gently wobble. Beta.","type":"boolean"},"hookIntro":{"description":"AI hook intro: Only for a pasted story or a Reddit post: open the video with one punchy hook line teasing the story's most shocking moment, then the story as it is written (a script without its formatting). On by default, as in the app. No extra credits. Default: true.","type":"boolean"},"cliffhanger":{"description":"End on a cliffhanger: Only for a video written from a topic: stop the story at the big reveal, so viewers want the next part. Off: the story gets a complete ending, as in the app. No extra credits. Default: false.","type":"boolean"},"delivery":{"description":"Who tells the story: narrator: a voice reads the story over the pictures, as always. characters: no narrator; realistic people say every line on camera with moving lips, each in their own voice (a voice on the character, including your own clone; pick it with v3.characters update). No narrator voice is needed: a voice sent is only for the first person with no voice of their own, and anyone without one gets a fitting voice. Topic videos in English only. Priced by the seconds filmed on speakModel.\nChoices:\n- narrator — Narrator: A voice reads the story over the pictures.\n- characters — AI Actors: No narrator: realistic people say every line on camera, each in their own voice.\nDefault: narrator.","type":"string","enum":["narrator","characters"]},"speakModel":{"description":"AI Actors: look: Only with delivery characters. seedanceMini (Realistic, 25 credits per second filmed): The best acting for the price. Faces hold from clip to clip. wan3 (Closest to your photo, 48 credits per second filmed): Natural skin and the nearest match to the picture. Calmer acting. seedance25 (Most cinematic, 85 credits per second filmed): Looks most like a real film. Softer picture, and the highest price. minimaxH3 (Lowest price, 24 credits per second filmed): Very real for one person. Can lose where people stand with three or more.\nChoices:\n- seedanceMini — Realistic: The best acting for the price. Faces hold from clip to clip.\n- wan3 — Closest to your photo: Natural skin and the nearest match to the picture. Calmer acting.\n- seedance25 — Most cinematic: Looks most like a real film. Softer picture, and the highest price.\n- minimaxH3 — Lowest price: Very real for one person. Can lose where people stand with three or more.\nDefault: seedanceMini.","type":"string","enum":["seedanceMini","wan3","seedance25","minimaxH3"]},"likenessRightsConfirmed":{"description":"I have the right to use these faces and voices: Required as true for delivery characters with your own characters: you confirm you have the right to use the face and voice of everyone you add. Default: false.","type":"boolean"},"watermarkType":{"description":"Watermark: Your text or picture on the video. Every plan.\nChoices:\n- none — None: No watermark.\n- text — Text: watermarkText.\n- image — Picture: watermarkMediaId.\nDefault: none.","type":"string","enum":["none","text","image"]},"watermarkText":{"description":"Text: The words. Default: No text (leave it out).","type":"string","minLength":1,"maxLength":50},"watermarkTextColor":{"description":"Text colour: #RRGGBB. Default: #FFFFFF.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundColor":{"description":"Box colour: #RRGGBB. Default: #000000.","type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"watermarkBackgroundOpacity":{"description":"Box: Box, 0 (none) to 1. From 0 to 1, in steps of 0.01. Default: 0.5.","type":"number","minimum":0,"maximum":1,"multipleOf":0.01},"watermarkMediaId":{"description":"A picture from autoclips_media, by id. Default: No picture (leave it out).","type":"string","pattern":"^[a-f0-9]{24}$"},"watermarkImageOpacity":{"description":"Picture opacity: 0.3 to 1. From 0.3 to 1, in steps of 0.01. Default: 0.7.","type":"number","minimum":0.3,"maximum":1,"multipleOf":0.01},"watermarkVerticalPosition":{"description":"Height: Percent from the top. From 10 to 90 percent. Default: 85.","type":"integer","minimum":10,"maximum":90},"watermarkHorizontalPosition":{"description":"Across: Percent from the left. From 5 to 95 percent. Default: 85.","type":"integer","minimum":5,"maximum":95},"watermarkScale":{"description":"Size: 1 is normal. From 0.5 to 3, in steps of 0.01. Default: 1.","type":"number","minimum":0.5,"maximum":3,"multipleOf":0.01},"watermarkStartSeconds":{"description":"From: Seconds into the video it appears. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"watermarkEndSeconds":{"description":"Until: Seconds into the video it goes; 0 = to the end. At least 0.5 s after the start. From 0 to 600 seconds, in steps of 0.1. Default: 0.","type":"number","minimum":0,"maximum":600,"multipleOf":0.1},"outroId":{"description":"Outro: An end card from autoclips_outros, after the last scene. Paid plans (free: plan_required). \"none\" = no outro. Default: No outro (leave it out).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"publishing":{"description":"Auto-post the finished video to your connected social accounts.","type":"object","properties":{"platforms":{"description":"Where to post the video automatically once it is rendered: any of tiktok, youtube, instagram, facebook, twitter. An empty list turns auto-posting off. Each platform needs a connected account, a monthly or annual plan that auto-posts, and a key with the publish permission.","maxItems":5,"type":"array","items":{"type":"string","enum":["tiktok","youtube","instagram","facebook","twitter"]}},"youtubePrivacy":{"description":"YouTube visibility. Default: private.","type":"string","enum":["private","unlisted","public"]},"aiDisclosure":{"description":"Label the post as AI-made where the platform supports it. Default: false.","type":"boolean"}},"required":["platforms"],"additionalProperties":false}},"additionalProperties":false},"example":{"imageModel":"seedream45","captions":false}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project id (from list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project id (from list or create).","example":"3f6c1a52-8d7e-4b1f-9a0c-2e5d7b9c4f10"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"description":"Where the project is: draft, generating-script, script-ready, generating-assets, assets-ready, generating-edl, edl-ready, rendering, completed, failed.","type":"string"},"stage":{"description":"The status in plain words.","type":"string"},"progress":{"type":"number"},"problem":{"description":"Why it stopped, when status is failed.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"settings":{"description":"The project's settings, in the same words the create and update actions take.","type":"object","properties":{},"additionalProperties":{}},"series":{"description":"Its place in a series. To make the next part, quick_create with series.previousProjectId set to this project's id: it starts from this project's settings, as the app's \"Create Part N\" does. The step-by-step way (a new draft from create, then v3_script generate with series) carries on the story only: the draft starts from the default settings (length, shape, language, look, featured characters), not this project's, unless you send them to create.","type":"object","properties":{"part":{"description":"Which part of a series this video is (1 for a video on its own).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"previousProjectId":{"description":"The project of the part before, when this one continues it.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["part","previousProjectId"],"additionalProperties":{}},"input":{"type":"object","properties":{},"additionalProperties":{}},"counts":{"type":"object","properties":{},"additionalProperties":{}},"video":{"description":"The finished video, once rendered.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"render":{"type":"object","properties":{},"additionalProperties":{}},"pipeline":{"description":"Quick Create progress, for projects made with quick_create. stalled is true when a run reads running but its server stopped (no sign of it for 5 minutes): retry carries it on.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"revisions":{"type":"object","properties":{},"additionalProperties":{}},"credits":{"description":"Credits already paid for the script and for the pictures and voice.","type":"object","properties":{},"additionalProperties":{}},"isDemo":{"type":"boolean"},"links":{"description":"Where to open the project in the app.","type":"object","properties":{},"additionalProperties":{}}},"required":["id","product","title","status","stage","progress","problem","createdAt","updatedAt","settings","series","input","counts","video","render","pipeline","revisions","credits","isDemo","links"],"additionalProperties":{}},"changed":{"type":"array","items":{"type":"string"}}},"required":["project","changed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"v3_projects_delete","summary":"Delete a V3 project for good. Not while it is generating or rendering.","description":"Deletes the project and its script, settings and edit. This cannot be undone. A project that is still generating or rendering, or that another request is starting a step on (for example a paid picture or render), cannot be deleted until that finishes or stops. A Quick Create run that stopped (no sign of it for 5 minutes) can be deleted. Demo projects cannot be deleted.\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"v3.projects.delete","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_projects action=delete","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project id (from list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project id (from list or create).","example":"3f6c1a52-8d7e-4b1f-9a0c-2e5d7b9c4f10"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"projectId":{"type":"string"},"title":{"type":"string"}},"required":["deleted","projectId","title"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"deleted":true,"projectId":"3f6c1a52-8d7e-4b1f-9a0c-2e5d7b9c4f10","title":"How volcanoes form"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/assets/generate":{"post":{"operationId":"v3_assets_generate","summary":"Make the pictures, voice and music for a project whose script is ready. Paid; answers with a job.","description":"Starts making the pictures, narration and background music for a project whose script is ready (status script-ready), or retries a project that stopped while making them. It costs credits, priced for the length the written script really runs (often a little longer or shorter than the length picked; the price says the length and the number of clips) and the settings saved on the project: the picture maker, consistent characters, premium sound effects, moving clips (and whether they are made straight from the script) with clip planning for each clip, music written for the video (music mode ai), and rendering the finished video. If the price for this script is higher by the time it starts, nothing is charged and the answer is 409 price_changed with the new price: ask for a new price. If the recording comes out shorter, the difference comes back by itself (credits.returnedForShorterVideo on the project). A retry only charges any difference from what was already paid. With consistent characters on, build the cast first (v3_cast build). A retry replaces the old timeline, which was built from the pictures that failed. Not while Quick Create is still making the project or a cast change is running. If the pictures cannot start (not enough credits, for example), nothing on the project changes. The narrator, voice model, language and music you send are saved on the project, so a retry uses them again. It answers with a job right away (status 202); follow it with autoclips_jobs get. When it succeeds, render the video (rendering is part of this price; rendering again is free).\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"v3.assets.generate","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"v3_production action=generate_assets","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"voice":{"description":"The narrator: a voice id or name from autoclips_voices (the library or your own cloned voices). Leave it out to keep the project's narrator, or the default one. With delivery characters (AI Actors) there is no narrator: each actor speaks in their own voice, and this voice is only for the first person who has none; left out, each of them gets a fitting voice.","type":"string","minLength":1,"maxLength":120},"voiceModel":{"description":"Which voice model reads the narration: eleven_v4 (Eleven v4), eleven_v3 (Eleven v3), eleven_multilingual_v2 (Multilingual v2). Leave it out to keep the project's voice model.","type":"string","enum":["eleven_v4","eleven_v3","eleven_multilingual_v2"]},"language":{"title":"Language (AutoClips V3 (cinematic stories) option language)","description":"Language: The language of the narration, captions and title.\nOne of 94 ids, too many to list in full here: call autoclips_options (GET /api/v1/options?product=v3&option=language) to see them all.\nChoices:\n- en — English: English narration and captions.\n- es — Spanish: Spanish narration and captions.\n- pt — Portuguese: Portuguese narration and captions.\n- fr — French: French narration and captions.\n- de — German: German narration and captions.\n- hi — Hindi: Hindi narration and captions.\n- ar — Arabic: Arabic narration and captions.\n- ja — Japanese: Japanese narration and captions.\n- zh — Chinese: Chinese narration and captions.\n- id — Indonesian: Indonesian narration and captions.\n- ru — Russian: Russian narration and captions.\n- tr — Turkish: Turkish narration and captions.\n- ko — Korean: Korean narration and captions.\n- it — Italian: Italian narration and captions.\n- nl — Dutch: Dutch narration and captions.\n- pl — Polish: Polish narration and captions.\n- ro — Romanian: Romanian narration and captions.\n- cs — Czech: Czech narration and captions.\n- sk — Slovak: Slovak narration and captions.\n- hu — Hungarian: Hungarian narration and captions.\n- sv — Swedish: Swedish narration and captions.\n- da — Danish: Danish narration and captions.\n- no — Norwegian: Norwegian narration and captions.\n- fi — Finnish: Finnish narration and captions.\n- is — Icelandic: Icelandic narration and captions.\n- et — Estonian: Estonian narration and captions.\n- lv — Latvian: Latvian narration and captions.\n- lt — Lithuanian: Lithuanian narration and captions.\n- el — Greek: Greek narration and captions.\n- bg — Bulgarian: Bulgarian narration and captions.\n…and 64 more.\nDefault: en.","type":"string"},"music":{"description":"Background music. Leave it out to keep the project's choice (auto when none was made).","type":"object","properties":{"mode":{"description":"auto: we pick a track that fits the story. ai: a new score written for this video (36 credits; if it cannot be made, they come back and a library track plays). none: no music. library: the track you name with trackId. upload: music you uploaded in the app, named with musicId.","type":"string","enum":["auto","ai","none","library","upload"]},"trackId":{"description":"Only with mode \"library\": the id of a track in the AutoClips music library (for example \"horror-dark-facts-04-creeping-dread-v1\"). An unknown id is refused with suggestions.","type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9_.-]+$"},"musicId":{"description":"Only with mode \"upload\": the id of music you uploaded in the app (its My Music tab) that one of your V3 videos already uses. Uploads are kept per browser, not per account, so that is how the API knows the music is yours. Send mode \"upload\" without musicId to get the ones you can pick (candidates).","type":"string","minLength":1,"maxLength":80,"pattern":"^[A-Za-z0-9-]+$"}},"required":["mode"],"additionalProperties":false},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project id (from v3 list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project id (from v3 list or create).","example":"6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job":{"description":"Follow it with autoclips_jobs get. It succeeds when the pictures and voice are ready.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"project":{"description":"The project after this step, in the same shape as reading the project.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"progress":{"type":"number"},"problem":{"anyOf":[{"type":"string"},{"type":"null"}]},"video":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"renderedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","thumbnailUrl","renderedAt"],"additionalProperties":false},{"type":"null"}]},"render":{"type":"object","properties":{"status":{"type":"string"},"progress":{"type":"number"}},"required":["status","progress"],"additionalProperties":false},"credits":{"type":"object","properties":{"script":{"type":"number"},"assets":{"type":"number"},"assetsLengthSeconds":{"description":"The length the pictures, voice and music were charged for: the script's real length, then the recording's once it is made.","anyOf":[{"type":"number"},{"type":"null"}]},"returnedForShorterVideo":{"description":"Credits given back because the recording ran shorter than the length charged for.","type":"number"}},"required":["script","assets"],"additionalProperties":{}},"links":{"type":"object","properties":{"app":{"type":"string"},"editor":{"type":"string"}},"required":["app","editor"],"additionalProperties":false}},"required":["id","product","title","status","stage","progress","problem","video","render","credits","links"],"additionalProperties":{}},"started":{"description":"False when this project was already being worked on by an earlier call; the job is that one.","type":"boolean"},"creditsCharged":{"description":"Credits this call charged (0 for a retry that cost no more than before).","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["job","project","started","creditsCharged"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"job":{"id":"job_0199a1b2c3d4e5f60718293a","product":"v3","kind":"v3.assets","resource":{"type":"project","id":"6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40"},"status":"running","step":"making pictures, voice and music","progress":5,"result":null,"error":null,"createdAt":"2026-09-28T10:02:00.000Z","updatedAt":"2026-09-28T10:02:00.000Z","finishedAt":null,"poll_after_seconds":10},"project":{"id":"6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40","product":"v3","title":"The Keeper of Flannan Isle","status":"generating-assets","stage":"Making pictures, voice and music","progress":5,"problem":null,"createdAt":"2026-09-28T09:40:00.000Z","updatedAt":"2026-09-28T10:02:00.000Z","settings":{"category":"horror","durationSeconds":60,"aspectRatio":"9:16","imageModel":"grokImagine","style":"realistic-4k","secondsPerImage":3,"scriptMode":"max","sfxMode":"standard","animation":"none","animationModel":"autoclips1","directVideo":false,"consistency":false,"language":"en","voiceId":null,"voiceModel":"eleven_v4","captions":true,"motionText":false,"subjectWobble":false,"hookIntro":null,"cliffhanger":false,"delivery":"narrator","speakModel":null,"likenessRightsConfirmed":false,"watermarkType":"none","watermarkText":null,"watermarkTextColor":"#FFFFFF","watermarkBackgroundColor":"#000000","watermarkBackgroundOpacity":0.5,"watermarkImageOpacity":0.7,"watermarkVerticalPosition":85,"watermarkHorizontalPosition":85,"watermarkScale":1,"watermarkStartSeconds":0,"watermarkEndSeconds":0,"outroId":null},"series":{"part":1,"previousProjectId":null},"input":{"mode":"topic","topic":"The lighthouse keeper who vanished","storyTitle":null,"hasStoryText":false,"redditUrl":null},"counts":{"scenes":3,"pictures":0,"picturesReady":0},"video":null,"render":{"status":"idle","progress":0},"pipeline":null,"revisions":{"script":0,"timeline":0},"credits":{"script":50,"assets":487,"assetsLengthSeconds":57.54,"returnedForShorterVideo":0},"isDemo":false,"links":{"app":"https://app.autoclips.app/create/cinematic-story?project=6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40","editor":"https://app.autoclips.app/editor/6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40"}},"started":true,"creditsCharged":487}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/cast/build":{"post":{"operationId":"v3_cast_build","summary":"Build the cast: find recurring characters and places, draw their sheets, plan who appears in each scene.","description":"For projects with consistent characters on, after the script is ready and before pictures are made. Reads the script, finds the recurring characters and places, draws a character sheet (four angles) for each character and a reference picture for each place, then plans which of them appear in each scene. Characters you picked from your library keep their own sheets. It runs in the background and answers with a job (usually a few minutes). Free here: the sheets are paid for later, through the doubled picture price, when the video's pictures are made. At most 3 builds per project; a new build replaces the whole cast and its shot plan. A build that stops halfway leaves the cast half built (its job says so) and does not count toward that limit: build it again before making pictures. It still needs a balance that covers the rest of the video's price (pictures with consistent characters, voice, music, any moving clips and sound effects, and the render, for the length the script really runs): without it, nothing is drawn.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.cast.build","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_cast action=build","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id (from v3_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The project id (from v3_projects list or create).","example":"6f1c2a9e-3b7d-4e21-9a0c-58d4b2e7f310"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"change":{"description":"What was started, in plain words.","type":"string"},"job":{"description":"The background work. Follow it with autoclips_jobs get.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"project":{"description":"The project as v3_projects get shows it, with its cast.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["change","job","project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"change":"Building the cast.","job":{"id":"job_01a0e7735350c3b9d2a5e817","product":"v3","kind":"v3.cast","resource":{"type":"project","id":"6f1c2a9e-3b7d-4e21-9a0c-58d4b2e7f310"},"status":"running","step":"reading the script for characters and places","progress":5,"result":null,"error":null,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","finishedAt":null,"poll_after_seconds":20},"project":{"id":"6f1c2a9e-3b7d-4e21-9a0c-58d4b2e7f310","product":"v3","title":"The Lighthouse Keeper","status":"script-ready","stage":"Script ready to review","settings":{"consistency":true,"imageModel":"seedream45"},"cast":{"savedCharacters":[],"characters":[],"locations":[],"failed":0,"shotsPlanned":0}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/cast/characters":{"post":{"operationId":"v3_cast_add_character","summary":"Add a character from your library (or a preset) to the cast, then re-plan who appears in each scene.","description":"Adds one of your own saved characters, or a preset, to a built cast. The character keeps its own sheet, so no picture is drawn. Then the shots are re-planned in the background (a job). Up to 6 characters per video. Only while the script is ready and before pictures are made.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.cast.add_character","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_cast action=add_character","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"characterId":{"description":"A character from your library or the presets (see v3_characters list).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"}},"required":["characterId"],"additionalProperties":false},"example":{"characterId":"c0a8e2f4-1d3b-4c5e-8f7a-9b0c1d2e3f40"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id (from v3_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The project id (from v3_projects list or create).","example":"6f1c2a9e-3b7d-4e21-9a0c-58d4b2e7f310"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"change":{"description":"What was started, in plain words.","type":"string"},"job":{"description":"The background work. Follow it with autoclips_jobs get.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"project":{"description":"The project as v3_projects get shows it, with its cast.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["change","job","project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"change":"Added Mira to the cast.","job":{"id":"job_01a0e7735350c3b9d2a5e817","product":"v3","kind":"v3.cast","resource":{"type":"project","id":"6f1c2a9e-3b7d-4e21-9a0c-58d4b2e7f310"},"status":"running","step":"planning who appears in each scene","progress":75,"result":null,"error":null,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","finishedAt":null,"poll_after_seconds":15},"project":{"id":"6f1c2a9e-3b7d-4e21-9a0c-58d4b2e7f310","product":"v3","title":"The Lighthouse Keeper","status":"script-ready","stage":"Script ready to review","settings":{"consistency":true,"imageModel":"seedream45"},"cast":{"savedCharacters":[],"characters":[{"id":"keeper_elias","name":"Elias","description":"A weathered man in his sixties, grey beard, navy wool coat.","sheetUrl":"https://media.autoclips.app/consistency-assets/v3-character-keeper_elias.jpg"},{"id":"saved_c0a8e2f4","name":"Mira","description":"A young sailor with short red hair and a yellow raincoat.","sheetUrl":"https://media.autoclips.app/v3-characters/c0a8e2f4-sheet.jpg"}],"locations":[{"id":"lighthouse_lamp_room","name":"Lamp room","referenceUrl":"https://media.autoclips.app/consistency-assets/v3-scene-lighthouse_lamp_room.jpg"}],"failed":0,"shotsPlanned":12}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/cast/characters/{castId}":{"delete":{"operationId":"v3_cast_remove_character","summary":"Remove a character from the cast, then re-plan who appears in each scene.","description":"Removes one character from a built cast (its id is in v3_projects get, include cast). A character from your library stays in your library. A character from an earlier part of the series keeps its picture in that part, and a new build brings it back while this part's script still has it. A drawn character's sheet is deleted, and getting it back needs a new build. Then the shots are re-planned in the background (a job). Only while the script is ready and before pictures are made.\n\n**Permissions:** edit, delete.\n**Cost:** Free.\n**Deletes data.**","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit","delete"]}],"x-autoclips-operation":"v3.cast.remove_character","x-autoclips-scopes":["edit","delete"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_cast action=remove_character","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id (from v3_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The project id (from v3_projects list or create).","example":"6f1c2a9e-3b7d-4e21-9a0c-58d4b2e7f310"},{"name":"castId","in":"path","required":true,"schema":{"description":"The cast member's id, from v3_projects get (include cast): cast.characters[].id.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The cast member's id, from v3_projects get (include cast): cast.characters[].id.","example":"harbor_master"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"change":{"description":"What was started, in plain words.","type":"string"},"job":{"description":"The background work. Follow it with autoclips_jobs get.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"project":{"description":"The project as v3_projects get shows it, with its cast.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["change","job","project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"change":"Removed Harbor master from the cast.","job":{"id":"job_01a0e7735350c3b9d2a5e817","product":"v3","kind":"v3.cast","resource":{"type":"project","id":"6f1c2a9e-3b7d-4e21-9a0c-58d4b2e7f310"},"status":"running","step":"planning who appears in each scene","progress":75,"result":null,"error":null,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","finishedAt":null,"poll_after_seconds":15},"project":{"id":"6f1c2a9e-3b7d-4e21-9a0c-58d4b2e7f310","product":"v3","title":"The Lighthouse Keeper","status":"script-ready","stage":"Script ready to review","settings":{"consistency":true,"imageModel":"seedream45"},"cast":{"savedCharacters":[],"characters":[{"id":"keeper_elias","name":"Elias","description":"A weathered man in his sixties, grey beard, navy wool coat.","sheetUrl":"https://media.autoclips.app/consistency-assets/v3-character-keeper_elias.jpg"}],"locations":[{"id":"lighthouse_lamp_room","name":"Lamp room","referenceUrl":"https://media.autoclips.app/consistency-assets/v3-scene-lighthouse_lamp_room.jpg"}],"failed":0,"shotsPlanned":12}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/cast/regenerate":{"post":{"operationId":"v3_cast_regenerate","summary":"Redraw one character sheet or place picture, optionally from a new description.","description":"Redraws one drawn character's sheet or one place's reference picture (ids from v3_projects get, include cast). Send description to change how it looks; it replaces that item's description, and the shots are then re-planned. Everything else in the cast stays as it is. Runs in the background (a job). Characters from your library are changed in the library instead. A character or place reused from an earlier part of the series is drawn new for this video; the earlier part keeps its own picture. At most 12 redraws per project. Only while the script is ready and before pictures are made.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.cast.regenerate","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_cast action=regenerate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"description":"character = a character sheet; location = a place's reference picture.","type":"string","enum":["character","location"]},"id":{"description":"The item's id from v3_projects get (include cast): cast.characters[].id or cast.locations[].id.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":{"description":"A new look, in plain words (10 to 1000 characters). It replaces the saved description. Leave it out to redraw from the saved one.","type":"string","minLength":10,"maxLength":1000}},"required":["kind","id"],"additionalProperties":false},"example":{"kind":"character","id":"keeper_elias","description":"A weathered man in his sixties with a short white beard, yellow oilskin coat and a knitted cap."}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The project id (from v3_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The project id (from v3_projects list or create).","example":"6f1c2a9e-3b7d-4e21-9a0c-58d4b2e7f310"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"change":{"description":"What was started, in plain words.","type":"string"},"job":{"description":"The background work. Follow it with autoclips_jobs get.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"project":{"description":"The project as v3_projects get shows it, with its cast.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["change","job","project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"change":"Drawing a new character sheet for Elias.","job":{"id":"job_01a0e7735350c3b9d2a5e817","product":"v3","kind":"v3.cast","resource":{"type":"project","id":"6f1c2a9e-3b7d-4e21-9a0c-58d4b2e7f310"},"status":"running","step":"drawing the new picture","progress":25,"result":null,"error":null,"createdAt":"2026-09-28T10:00:00.000Z","updatedAt":"2026-09-28T10:00:00.000Z","finishedAt":null,"poll_after_seconds":15},"project":{"id":"6f1c2a9e-3b7d-4e21-9a0c-58d4b2e7f310","product":"v3","title":"The Lighthouse Keeper","status":"script-ready","stage":"Script ready to review","settings":{"consistency":true,"imageModel":"seedream45"},"cast":{"savedCharacters":[],"characters":[{"id":"keeper_elias","name":"Elias","description":"A weathered man in his sixties, grey beard, navy wool coat.","sheetUrl":"https://media.autoclips.app/consistency-assets/v3-character-keeper_elias.jpg"}],"locations":[{"id":"lighthouse_lamp_room","name":"Lamp room","referenceUrl":"https://media.autoclips.app/consistency-assets/v3-scene-lighthouse_lamp_room.jpg"}],"failed":0,"shotsPlanned":12}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/cast/{castId}/save":{"post":{"operationId":"v3_characters_save_from_project","summary":"Keep a cast member of one of your V3 projects as a saved character. Free.","description":"Copies the cast member's character sheet from the project into your character library, so you can use the same face in future videos. Saving the same cast member again returns the character already saved (alreadySaved true, status 200). The project's pictures must be made first: the cast's character sheets are paid for with them.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.characters.save_from_project","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_characters action=save_from_project","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The character's name, 2 to 40 characters.","type":"string","minLength":2,"maxLength":40}},"additionalProperties":false},"example":{"name":"Detective Sam"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project the cast member is in.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project the cast member is in.","example":"v3_8f14e45fceea167a"},{"name":"castId","in":"path","required":true,"schema":{"description":"The cast member's id in that project (v3_projects get with include cast: cast.characters[].id).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The cast member's id in that project (v3_projects get with include cast: cast.characters[].id).","example":"detective_sam"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"character":{"type":"object","properties":{"id":{"description":"The character id. Use it to put the character in a V3 video, or with get, update, delete, regenerate_sheet and build_sheet.","type":"string"},"name":{"type":"string"},"description":{"description":"How the character looks, in words. The AI uses it with the sheet.","type":"string"},"sheetUrl":{"description":"The reference sheet picture that keeps the face the same in every scene.","anyOf":[{"type":"string"},{"type":"null"}]},"sheets":{"description":"Every sheet this character has had, oldest first (the last 20). Empty for a character whose sheet has not changed since AutoClips began keeping them. Switching back to one with update (sheetUrl) is free.","type":"array","items":{"type":"object","properties":{"url":{"description":"The sheet picture. Send it as sheetUrl to update to make it the character's sheet again.","type":"string"},"label":{"description":"What made it: the model's name, or \"From your photos\" for a sheet built from photos.","type":"string"},"model":{"description":"The model picked for it (grokImagine, seedream45, krea2Medium, seedream5Pro), or grounded for a sheet built from photos; null when not recorded.","anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"description":"generated (drawn from the description) or grounded (built from photos); older sheets can carry the character's source.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"current":{"description":"True for the sheet the character uses now.","type":"boolean"}},"required":["url","label","model","kind","createdAt","current"],"additionalProperties":false}},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"generated (drawn from a description), uploaded (from photos), from-video (saved from a project) or preset (an AutoClips starter character).","type":"string"},"isPreset":{"description":"True for AutoClips starter characters. Everyone can use them; nobody can change them.","type":"boolean"},"style":{"description":"The V3 style it was drawn in, when it was one of the V3 styles.","anyOf":[{"type":"string"},{"type":"null"}]},"photos":{"description":"The photos it was made from (characters made from photos only).","type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"view":{"anyOf":[{"type":"string","enum":["front","three-quarter","side","back","smiling","other"]},{"type":"null"}]}},"required":["url","view"],"additionalProperties":false}},"hasPhotoSheet":{"description":"True once build_sheet has turned the photos into a turnaround sheet.","type":"boolean"},"voice":{"description":"The character's own voice, used when the character speaks in character clips.","anyOf":[{"type":"object","properties":{"voiceId":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string","enum":["library","cloned"]}},"required":["voiceId","name","source"],"additionalProperties":false},{"type":"null"}]},"usageCount":{"description":"How many videos used it.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"canChange":{"description":"You can rename it, describe it, give it a voice, switch back to an earlier sheet or delete it.","type":"boolean"},"canRegenerateSheet":{"description":"regenerate_sheet works for it (characters drawn from a description).","type":"boolean"},"canBuildSheet":{"description":"build_sheet works for it (characters made from photos).","type":"boolean"}},"required":["id","name","description","sheetUrl","sheets","thumbnailUrl","source","isPreset","style","photos","hasPhotoSheet","voice","usageCount","createdAt","updatedAt","canChange","canRegenerateSheet","canBuildSheet"],"additionalProperties":false},"alreadySaved":{"description":"True when this cast member was already in your library; nothing new was made.","type":"boolean"}},"required":["character","alreadySaved"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"character":{"id":"4c2e8a1b-9d3f-4e5a-b6c7-8d9e0f1a2b3c","name":"Detective Sam","description":"A 30-year-old baker with curly red hair tied up, freckles, a flour-dusted green apron over a white shirt.","sheetUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-detective-sam-4c2e8a1b/sheet-1758358800000.jpg","sheets":[],"thumbnailUrl":"https://media.autoclips.app/v3-characters/5dc8655f-0000-4000-8000-000000000000/v3-detective-sam-4c2e8a1b/sheet-1758358800000.jpg","source":"from-video","isPreset":false,"style":null,"photos":[],"hasPhotoSheet":false,"voice":null,"usageCount":2,"createdAt":"2026-09-20T09:00:00.000Z","updatedAt":"2026-09-25T14:30:00.000Z","canChange":true,"canRegenerateSheet":false,"canBuildSheet":false},"alreadySaved":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/render":{"post":{"operationId":"v3_render_start","summary":"Render the video file. Free once the assets are paid; builds the timeline first if needed. Answers with a job.","description":"Renders the project into a video file on our render servers. It is free once the pictures and voice are paid for, and you can render again after changes; your plan's daily video limit applies. If the timeline is not built yet (or was built before the pictures were made again) it is built first. This render makes the video from the cut the project was made with, so a project with saved timeline-editor edits is refused, and the answer gives the ways to a video: press Render in the editor (the project's links.editor; a V3 timeline is not rendered through the API yet), or undo edits made through the API back to the made cut (autoclips_timeline undo), then render here. Not while Quick Create is still making the project. It answers with a job right away (status 202); follow it with autoclips_jobs get. When it succeeds, the job result and the project hold the video link. If the project has auto-posting turned on and was never rendered before, the finished video is posted to those accounts (as on the website): in AI apps it asks first, it needs a key with the publish permission, and the answer lists the accounts in autoPost.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.render.start","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_production action=render","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project id (from v3 list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project id (from v3 list or create).","example":"6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job":{"description":"Follow it with autoclips_jobs get. When it succeeds, result.videoUrl is the video.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"project":{"description":"The project after this step, in the same shape as reading the project.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"progress":{"type":"number"},"problem":{"anyOf":[{"type":"string"},{"type":"null"}]},"video":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"renderedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","thumbnailUrl","renderedAt"],"additionalProperties":false},{"type":"null"}]},"render":{"type":"object","properties":{"status":{"type":"string"},"progress":{"type":"number"}},"required":["status","progress"],"additionalProperties":false},"credits":{"type":"object","properties":{"script":{"type":"number"},"assets":{"type":"number"},"assetsLengthSeconds":{"description":"The length the pictures, voice and music were charged for: the script's real length, then the recording's once it is made.","anyOf":[{"type":"number"},{"type":"null"}]},"returnedForShorterVideo":{"description":"Credits given back because the recording ran shorter than the length charged for.","type":"number"}},"required":["script","assets"],"additionalProperties":{}},"links":{"type":"object","properties":{"app":{"type":"string"},"editor":{"type":"string"}},"required":["app","editor"],"additionalProperties":false}},"required":["id","product","title","status","stage","progress","problem","video","render","credits","links"],"additionalProperties":{}},"started":{"description":"False when this project was already rendering from an earlier call; the job is that one.","type":"boolean"},"autoPost":{"description":"Social platforms the finished video will be posted to automatically, from the project's publishing settings. Empty when nothing will be posted.","type":"array","items":{"type":"string","enum":["tiktok","youtube","instagram","facebook","twitter","snapchat"]}}},"required":["job","project","started","autoPost"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"job":{"id":"job_0199a1c4d5e6f70812233445","product":"v3","kind":"v3.render","resource":{"type":"project","id":"6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40"},"status":"running","step":"rendering","progress":0,"result":null,"error":null,"createdAt":"2026-09-28T10:02:00.000Z","updatedAt":"2026-09-28T10:02:00.000Z","finishedAt":null,"poll_after_seconds":10},"project":{"id":"6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40","product":"v3","title":"The Keeper of Flannan Isle","status":"rendering","stage":"Rendering the video","progress":0,"problem":null,"createdAt":"2026-09-28T09:40:00.000Z","updatedAt":"2026-09-28T10:02:00.000Z","settings":{"category":"horror","durationSeconds":60,"aspectRatio":"9:16","imageModel":"grokImagine","style":"realistic-4k","secondsPerImage":3,"scriptMode":"max","sfxMode":"standard","animation":"none","animationModel":"autoclips1","directVideo":false,"consistency":false,"language":"en","voiceId":null,"voiceModel":"eleven_v4","captions":true,"motionText":false,"subjectWobble":false,"hookIntro":null,"cliffhanger":false,"delivery":"narrator","speakModel":null,"likenessRightsConfirmed":false,"watermarkType":"none","watermarkText":null,"watermarkTextColor":"#FFFFFF","watermarkBackgroundColor":"#000000","watermarkBackgroundOpacity":0.5,"watermarkImageOpacity":0.7,"watermarkVerticalPosition":85,"watermarkHorizontalPosition":85,"watermarkScale":1,"watermarkStartSeconds":0,"watermarkEndSeconds":0,"outroId":null},"series":{"part":1,"previousProjectId":null},"input":{"mode":"topic","topic":"The lighthouse keeper who vanished","storyTitle":null,"hasStoryText":false,"redditUrl":null},"counts":{"scenes":3,"pictures":0,"picturesReady":0},"video":null,"render":{"status":"rendering","progress":0},"pipeline":null,"revisions":{"script":0,"timeline":0},"credits":{"script":50,"assets":487,"assetsLengthSeconds":57.54,"returnedForShorterVideo":0},"isDemo":false,"links":{"app":"https://app.autoclips.app/create/cinematic-story?project=6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40","editor":"https://app.autoclips.app/editor/6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40"}},"started":true,"autoPost":[]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/render/cancel":{"post":{"operationId":"v3_render_cancel","summary":"Stop a render that is running. Free; nothing is refunded because renders cost nothing.","description":"Stops the project's running render and puts it back to ready-to-render. Renders are free, so there is nothing to refund. In the first minute or two of a render it is still being handed to the render service and cannot be stopped yet; the answer then says to try again shortly. Known race: the render's own watcher notices the stop a few seconds later and may mark the project as failed; the render job still shows as canceled, and rendering again works either way. It also stops the render of a Quick Create run that stopped (no sign of it for 5 minutes); that run still holds the project until v3_projects retry carries it on or the project is deleted.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.render.cancel","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_production action=cancel_render","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project id (from v3 list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project id (from v3 list or create).","example":"6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"description":"The project after this step, in the same shape as reading the project.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"progress":{"type":"number"},"problem":{"anyOf":[{"type":"string"},{"type":"null"}]},"video":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"renderedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","thumbnailUrl","renderedAt"],"additionalProperties":false},{"type":"null"}]},"render":{"type":"object","properties":{"status":{"type":"string"},"progress":{"type":"number"}},"required":["status","progress"],"additionalProperties":false},"credits":{"type":"object","properties":{"script":{"type":"number"},"assets":{"type":"number"},"assetsLengthSeconds":{"description":"The length the pictures, voice and music were charged for: the script's real length, then the recording's once it is made.","anyOf":[{"type":"number"},{"type":"null"}]},"returnedForShorterVideo":{"description":"Credits given back because the recording ran shorter than the length charged for.","type":"number"}},"required":["script","assets"],"additionalProperties":{}},"links":{"type":"object","properties":{"app":{"type":"string"},"editor":{"type":"string"}},"required":["app","editor"],"additionalProperties":false}},"required":["id","product","title","status","stage","progress","problem","video","render","credits","links"],"additionalProperties":{}},"canceled":{"type":"boolean"},"message":{"type":"string"}},"required":["project","canceled","message"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40","product":"v3","title":"The Keeper of Flannan Isle","status":"edl-ready","stage":"Ready to render","progress":80,"problem":null,"createdAt":"2026-09-28T09:40:00.000Z","updatedAt":"2026-09-28T10:02:00.000Z","settings":{"category":"horror","durationSeconds":60,"aspectRatio":"9:16","imageModel":"grokImagine","style":"realistic-4k","secondsPerImage":3,"scriptMode":"max","sfxMode":"standard","animation":"none","animationModel":"autoclips1","directVideo":false,"consistency":false,"language":"en","voiceId":null,"voiceModel":"eleven_v4","captions":true,"motionText":false,"subjectWobble":false,"hookIntro":null,"cliffhanger":false,"delivery":"narrator","speakModel":null,"likenessRightsConfirmed":false,"watermarkType":"none","watermarkText":null,"watermarkTextColor":"#FFFFFF","watermarkBackgroundColor":"#000000","watermarkBackgroundOpacity":0.5,"watermarkImageOpacity":0.7,"watermarkVerticalPosition":85,"watermarkHorizontalPosition":85,"watermarkScale":1,"watermarkStartSeconds":0,"watermarkEndSeconds":0,"outroId":null},"series":{"part":1,"previousProjectId":null},"input":{"mode":"topic","topic":"The lighthouse keeper who vanished","storyTitle":null,"hasStoryText":false,"redditUrl":null},"counts":{"scenes":3,"pictures":0,"picturesReady":0},"video":null,"render":{"status":"idle","progress":0},"pipeline":null,"revisions":{"script":0,"timeline":0},"credits":{"script":50,"assets":487,"assetsLengthSeconds":57.54,"returnedForShorterVideo":0},"isDemo":false,"links":{"app":"https://app.autoclips.app/create/cinematic-story?project=6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40","editor":"https://app.autoclips.app/editor/6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40"}},"canceled":true,"message":"The render was stopped. Its own watcher may still mark the project as failed a few seconds later; that is expected. Render again whenever you like (free)."}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/retry":{"post":{"operationId":"v3_projects_retry","summary":"Carry on a V3 project that stopped with a problem, from where it stopped. Steps already paid for are not charged again.","description":"For a project whose status is failed, or whose Quick Create run stopped without failing (no sign of it for 5 minutes, after its server restarted, say: its job says so). A stopped Quick Create run is carried on from where it stopped, keeping every step it finished, as the app's own recovery does; it is priced at what is left (a step already paid is not charged again, so often 0) and answers with its job. Otherwise only a failed project: a Quick Create project that stopped before its script was written, or while drawing its characters and places before any picture, runs Quick Create again from the start (script, characters, pictures and voice, edit, render), as the app's Retry does; its price is the most that run can be charged (for a script as long as the narration may be), so it usually costs less, and the notes give the expected price. Any other project, Quick Create ones included, keeps what is already made and re-runs the one step that stopped: the script, the pictures and voice, the edit or the render; carry on with v3_production after that. The pictures step keeps the project's music (a library track, or music uploaded in the app, read again by its id); saved music that is gone (deleted in the app, or taken off the library) is refused with 409 saved_music_unavailable: make the pictures with v3_production generate_assets and pick music. A pasted or Reddit story whose script is written again is priced at the length it needs (the script step raises the length to fit the story, and everything after it is charged at that length); the price says so. Steps already paid for are not charged again (the pictures step only charges a difference if the settings now cost more), so the price is often 0. A retry that can finish the project's first render posts the video to its auto-post accounts: the price says so, and it needs the publish permission; if the step that would run now posts and the approved price did not say so, nothing starts (409 consent_changed: ask for a new price). Answers with a job. A project can be retried step by step 5 times. The same request again with the same Idempotency-Key hands back the same job.\n\n**Permissions:** spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["spend"]}],"x-autoclips-operation":"v3.projects.retry","x-autoclips-scopes":["spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"v3_projects action=retry","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project id (from list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project id (from list or create).","example":"3f6c1a52-8d7e-4b1f-9a0c-2e5d7b9c4f10"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"project":{"type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"description":"Where the project is: draft, generating-script, script-ready, generating-assets, assets-ready, generating-edl, edl-ready, rendering, completed, failed.","type":"string"},"stage":{"description":"The status in plain words.","type":"string"},"progress":{"type":"number"},"problem":{"description":"Why it stopped, when status is failed.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"settings":{"description":"The project's settings, in the same words the create and update actions take.","type":"object","properties":{},"additionalProperties":{}},"series":{"description":"Its place in a series. To make the next part, quick_create with series.previousProjectId set to this project's id: it starts from this project's settings, as the app's \"Create Part N\" does. The step-by-step way (a new draft from create, then v3_script generate with series) carries on the story only: the draft starts from the default settings (length, shape, language, look, featured characters), not this project's, unless you send them to create.","type":"object","properties":{"part":{"description":"Which part of a series this video is (1 for a video on its own).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"previousProjectId":{"description":"The project of the part before, when this one continues it.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["part","previousProjectId"],"additionalProperties":{}},"input":{"type":"object","properties":{},"additionalProperties":{}},"counts":{"type":"object","properties":{},"additionalProperties":{}},"video":{"description":"The finished video, once rendered.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"render":{"type":"object","properties":{},"additionalProperties":{}},"pipeline":{"description":"Quick Create progress, for projects made with quick_create. stalled is true when a run reads running but its server stopped (no sign of it for 5 minutes): retry carries it on.","anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"revisions":{"type":"object","properties":{},"additionalProperties":{}},"credits":{"description":"Credits already paid for the script and for the pictures and voice.","type":"object","properties":{},"additionalProperties":{}},"isDemo":{"type":"boolean"},"links":{"description":"Where to open the project in the app.","type":"object","properties":{},"additionalProperties":{}}},"required":["id","product","title","status","stage","progress","problem","createdAt","updatedAt","settings","series","input","counts","video","render","pipeline","revisions","credits","isDemo","links"],"additionalProperties":{}}},"required":["job","project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/scenes/{scene}/edit-image":{"post":{"operationId":"v3_scenes_edit_image","summary":"Edit a scene's picture with AI from a plain-words instruction, and put the result on the scene. Costs credits.","description":"Sends the scene's current picture and your instruction to an AI picture editor, then puts the edited picture on the scene (and on the timeline, once there is one). Costs 8 (grokImagine), 5 (fluxSchnell), 5 (fluxDev), 10 (seedream45), 10 (fluxPro), 30 (nanoBanana2), 10 (seedream5Flash) credits per edit, times your plan's price multiplier; the quote shows the exact number. Takes up to a minute. The edited picture is also saved in your media library. If the edit fails, its credits are given back.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"v3.scenes.edit_image","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"v3_scenes action=edit_image","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"picture":{"description":"Which of the scene's pictures, from 1, when the scene shows more than one one after the other (the answer says how many). Leave it out when the scene has one picture.","type":"integer","minimum":1,"maximum":50},"instruction":{"description":"What to change, in plain words. Example: \"make it night time with a full moon\".","type":"string","minLength":3,"maxLength":1000},"model":{"description":"The AI that edits the picture. Prices per edit: grokImagine 8, fluxSchnell 5, fluxDev 5, seedream45 10, fluxPro 10, nanoBanana2 30, seedream5Flash 10 credits (times your plan's price multiplier). Default: the project's picture maker when it can edit, else grokImagine.","type":"string","enum":["grokImagine","fluxSchnell","fluxDev","seedream45","fluxPro","nanoBanana2","seedream5Flash"]},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"required":["instruction"],"additionalProperties":false},"example":{"picture":1,"instruction":"make it night time with a full moon over the sea"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project id, from v3_projects list.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project id, from v3_projects list.","example":"3f6c1b2a-9d4e-4f11-8a2b-5c7d9e0f1a2b"},{"name":"scene","in":"path","required":true,"schema":{"description":"The scene number, from 1, as shown by v3_projects get with include=script.","type":"integer","minimum":1,"maximum":500},"description":"The scene number, from 1, as shown by v3_projects get with include=script.","example":3},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"description":"The project, as v3_projects get shows it.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"}},"required":["id","product","title","status","stage"],"additionalProperties":{}},"scene":{"type":"object","properties":{"number":{"description":"The scene number (from 1).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"picture":{"description":"Which of the scene's pictures changed (from 1).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pictures":{"description":"How many pictures the scene shows, one after the other.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clip":{"description":"When every scene moves: the 5-second clip this picture belongs to. Otherwise null.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"url":{"description":"The new picture.","type":"string"},"mediaId":{"description":"The new picture in your media library.","type":"string"},"onTimeline":{"description":"True when the project already had a timeline and it was updated too.","type":"boolean"},"needsRender":{"description":"True when the project already has a finished video: render again to see the change in it.","type":"boolean"},"previous":{"description":"The picture it replaced. To undo, call set_image with previous.mediaId.","type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"mediaId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","mediaId"],"additionalProperties":false}},"required":["number","picture","pictures","clip","url","mediaId","onTimeline","needsRender","previous"],"additionalProperties":false},"model":{"description":"The AI that edited the picture.","type":"string","enum":["grokImagine","fluxSchnell","fluxDev","seedream45","fluxPro","nanoBanana2","seedream5Flash"]}},"required":["project","scene","model"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"3f6c1b2a-9d4e-4f11-8a2b-5c7d9e0f1a2b","product":"v3","title":"The Lighthouse Keeper","status":"edl-ready","stage":"Ready to render","progress":80,"problem":null,"links":{"app":"https://app.autoclips.app/create/cinematic-story?project=3f6c1b2a-9d4e-4f11-8a2b-5c7d9e0f1a2b","editor":"https://app.autoclips.app/editor/3f6c1b2a-9d4e-4f11-8a2b-5c7d9e0f1a2b"}},"scene":{"number":3,"picture":1,"pictures":2,"clip":null,"url":"https://media.autoclips.app/v3-images/scene-3/m2q8a-edited.jpg","mediaId":"66f7c0ffee00000000000002","onTimeline":true,"needsRender":false,"previous":{"url":"https://media.autoclips.app/v3-images/scene-3/lx9k2.jpg","mediaId":"66f7c0ffee000000000000a3"}},"model":"grokImagine"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/scenes/{scene}/image":{"put":{"operationId":"v3_scenes_set_image","summary":"Put a picture from your media library on a scene (upload it with autoclips_media first).","description":"Replaces the picture a scene shows with one from your media library, in the saved project and, once there is a timeline, on the timeline too. Free. A scene that shows several pictures one after the other needs `picture` (from 1). Moving clips, and projects with saved timeline-editor edits, are changed on the timeline instead (autoclips_timeline edit with a replace_media operation). The answer names the picture it replaced, so it can be put back.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.scenes.set_image","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_scenes action=set_image","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"picture":{"description":"Which of the scene's pictures, from 1, when the scene shows more than one one after the other (the answer says how many). Leave it out when the scene has one picture.","type":"integer","minimum":1,"maximum":50},"mediaId":{"description":"A picture from your media library (autoclips_media list, upload_link or import_url). It must be a picture, not a video or a sound.","type":"string","pattern":"^[a-fA-F0-9]{24}$"}},"required":["mediaId"],"additionalProperties":false},"example":{"picture":1,"mediaId":"66f7c0ffee00000000000001"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project id, from v3_projects list.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project id, from v3_projects list.","example":"3f6c1b2a-9d4e-4f11-8a2b-5c7d9e0f1a2b"},{"name":"scene","in":"path","required":true,"schema":{"description":"The scene number, from 1, as shown by v3_projects get with include=script.","type":"integer","minimum":1,"maximum":500},"description":"The scene number, from 1, as shown by v3_projects get with include=script.","example":3},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"description":"The project, as v3_projects get shows it.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"}},"required":["id","product","title","status","stage"],"additionalProperties":{}},"scene":{"type":"object","properties":{"number":{"description":"The scene number (from 1).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"picture":{"description":"Which of the scene's pictures changed (from 1).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pictures":{"description":"How many pictures the scene shows, one after the other.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clip":{"description":"When every scene moves: the 5-second clip this picture belongs to. Otherwise null.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"url":{"description":"The new picture.","type":"string"},"mediaId":{"description":"The new picture in your media library.","type":"string"},"onTimeline":{"description":"True when the project already had a timeline and it was updated too.","type":"boolean"},"needsRender":{"description":"True when the project already has a finished video: render again to see the change in it.","type":"boolean"},"previous":{"description":"The picture it replaced. To undo, call set_image with previous.mediaId.","type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"mediaId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","mediaId"],"additionalProperties":false}},"required":["number","picture","pictures","clip","url","mediaId","onTimeline","needsRender","previous"],"additionalProperties":false}},"required":["project","scene"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"3f6c1b2a-9d4e-4f11-8a2b-5c7d9e0f1a2b","product":"v3","title":"The Lighthouse Keeper","status":"edl-ready","stage":"Ready to render","progress":80,"problem":null,"links":{"app":"https://app.autoclips.app/create/cinematic-story?project=3f6c1b2a-9d4e-4f11-8a2b-5c7d9e0f1a2b","editor":"https://app.autoclips.app/editor/3f6c1b2a-9d4e-4f11-8a2b-5c7d9e0f1a2b"}},"scene":{"number":3,"picture":1,"pictures":2,"clip":null,"url":"https://media.autoclips.app/clips/character-explainer/user_123/api/7d1f0c3e.jpg","mediaId":"66f7c0ffee00000000000001","onTimeline":true,"needsRender":false,"previous":{"url":"https://media.autoclips.app/v3-images/scene-3/lx9k2.jpg","mediaId":"66f7c0ffee000000000000a3"}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/scenes/{scene}/image-search":{"post":{"operationId":"v3_scenes_search_images","summary":"Search the web for pictures for a scene. Show them to the user, then use_web_image with the chosen resultId.","description":"Finds up to 10 real photos on the web for a scene, using its narration or your own search words. Free, within the daily limit for free AI helpers. Each result has a resultId that use_web_image accepts for 30 minutes. Pictures from the web may be owned by others: pick ones the user may use.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.scenes.search_images","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_scenes action=search_images","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"description":"What to search for. Default: the scene's own narration.","type":"string","minLength":2,"maxLength":200}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project id, from v3_projects list.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project id, from v3_projects list.","example":"3f6c1b2a-9d4e-4f11-8a2b-5c7d9e0f1a2b"},{"name":"scene","in":"path","required":true,"schema":{"description":"The scene number, from 1, as shown by v3_projects get with include=script.","type":"integer","minimum":1,"maximum":500},"description":"The scene number, from 1, as shown by v3_projects get with include=script.","example":2},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string"},"scene":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"query":{"description":"What was searched for.","type":"string"},"expiresAt":{"description":"The resultIds work until this time.","type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"resultId":{"description":"Pass this to use_web_image to put the picture on a scene.","type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"The website the picture is from.","anyOf":[{"type":"string"},{"type":"null"}]},"width":{"anyOf":[{"type":"number"},{"type":"null"}]},"height":{"anyOf":[{"type":"number"},{"type":"null"}]},"imageUrl":{"description":"The picture on the web, to show the user.","type":"string"},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["resultId","title","source","width","height","imageUrl","thumbnailUrl"],"additionalProperties":false}}},"required":["projectId","scene","query","expiresAt","results"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"projectId":"3f6c1b2a-9d4e-4f11-8a2b-5c7d9e0f1a2b","scene":2,"query":"The old lighthouse stood alone on the cliff","expiresAt":"2026-09-28T10:30:00.000Z","results":[{"resultId":"ws0123456789abcdef_1","title":"Lighthouse at dusk","source":"example.org","width":1600,"height":1067,"imageUrl":"https://images.example.org/lighthouse.jpg","thumbnailUrl":"https://images.example.org/lighthouse-thumb.jpg"}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/scenes/{scene}/web-image":{"post":{"operationId":"v3_scenes_use_web_image","summary":"Put a picture from search_images on a scene. It is saved to your media library too.","description":"Downloads a picture that search_images offered for this project (by its resultId, within 30 minutes), saves it to your media library and puts it on the scene, and on the timeline once there is one. Free, within the daily upload limit. A scene that shows several pictures needs `picture` (from 1).\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.scenes.use_web_image","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_scenes action=use_web_image","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"picture":{"description":"Which of the scene's pictures, from 1, when the scene shows more than one one after the other (the answer says how many). Leave it out when the scene has one picture.","type":"integer","minimum":1,"maximum":50},"resultId":{"description":"The resultId of a picture from search_images on this project (valid for 30 minutes).","type":"string","pattern":"^(ws[a-f0-9]{16})_([0-9]{1,2})$"}},"required":["resultId"],"additionalProperties":false},"example":{"resultId":"ws0123456789abcdef_1"}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project id, from v3_projects list.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project id, from v3_projects list.","example":"3f6c1b2a-9d4e-4f11-8a2b-5c7d9e0f1a2b"},{"name":"scene","in":"path","required":true,"schema":{"description":"The scene number, from 1, as shown by v3_projects get with include=script.","type":"integer","minimum":1,"maximum":500},"description":"The scene number, from 1, as shown by v3_projects get with include=script.","example":2},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"description":"The project, as v3_projects get shows it.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"}},"required":["id","product","title","status","stage"],"additionalProperties":{}},"scene":{"type":"object","properties":{"number":{"description":"The scene number (from 1).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"picture":{"description":"Which of the scene's pictures changed (from 1).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pictures":{"description":"How many pictures the scene shows, one after the other.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clip":{"description":"When every scene moves: the 5-second clip this picture belongs to. Otherwise null.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"url":{"description":"The new picture.","type":"string"},"mediaId":{"description":"The new picture in your media library.","type":"string"},"onTimeline":{"description":"True when the project already had a timeline and it was updated too.","type":"boolean"},"needsRender":{"description":"True when the project already has a finished video: render again to see the change in it.","type":"boolean"},"previous":{"description":"The picture it replaced. To undo, call set_image with previous.mediaId.","type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"mediaId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","mediaId"],"additionalProperties":false}},"required":["number","picture","pictures","clip","url","mediaId","onTimeline","needsRender","previous"],"additionalProperties":false}},"required":["project","scene"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"3f6c1b2a-9d4e-4f11-8a2b-5c7d9e0f1a2b","product":"v3","title":"The Lighthouse Keeper","status":"edl-ready","stage":"Ready to render","progress":80,"problem":null,"links":{"app":"https://app.autoclips.app/create/cinematic-story?project=3f6c1b2a-9d4e-4f11-8a2b-5c7d9e0f1a2b","editor":"https://app.autoclips.app/editor/3f6c1b2a-9d4e-4f11-8a2b-5c7d9e0f1a2b"}},"scene":{"number":2,"picture":1,"pictures":1,"clip":null,"url":"https://media.autoclips.app/v3-images/v3-web/3f6c1b2a/web-scene-2-a1b2.jpg","mediaId":"66f7c0ffee00000000000004","onTimeline":true,"needsRender":false,"previous":{"url":"https://media.autoclips.app/v3-images/scene-3/lx9k2.jpg","mediaId":"66f7c0ffee000000000000a3"}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/script":{"patch":{"operationId":"v3_script_edit","summary":"Change the script: narration, mood or picture of a scene; add, delete or move scenes; pick a hook line; rename.","description":"Applies up to 20 changes in order, all or nothing, and saves them as the next script revision. Free. Scenes are numbered from 1 as in the script you read; those numbers keep meaning the same scenes for the whole batch, even after an earlier change added or deleted scenes. move_scene \"to\" is a position in the list as it stands at that point. expectedRevision is required: revisions.script from the project you read. If the script changed since, nothing is saved and the answer is revision_conflict: read it again and redo the change. So a batch sent twice (a retry) is never applied twice. Limits follow the video length: the number of scenes, the narration per scene and in total. Every other detail of a scene you do not touch is kept. Allowed until the pictures are made (status script-ready, or stopped before pictures). undo brings back the previous version.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.script.edit","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_script action=edit","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedRevision":{"description":"The script revision you read (revisions.script). A stale batch is refused instead of changing the wrong scenes.","type":"integer","minimum":0,"maximum":9007199254740991},"operations":{"description":"Up to 20 changes, applied in order: set_narration, set_mood, set_description, add_scene, delete_scene, move_scene, use_hook, set_title.","minItems":1,"maxItems":20,"type":"array","items":{"anyOf":[{"description":"Replace what the narrator says in one scene.","type":"object","properties":{"op":{"type":"string","const":"set_narration"},"scene":{"description":"A scene number from the script you read (1 = the first scene). Numbers always mean the script as you read it, even after an earlier operation in the same batch added or deleted scenes.","type":"integer","minimum":1,"maximum":250},"text":{"description":"What the narrator says in this scene, in the video's language. One scene holds up to about 40% of the whole narration (at most 2,000 characters).","type":"string","minLength":1,"maxLength":2000}},"required":["op","scene","text"],"additionalProperties":false},{"description":"Change one scene's mood.","type":"object","properties":{"op":{"type":"string","const":"set_mood"},"scene":{"description":"A scene number from the script you read (1 = the first scene). Numbers always mean the script as you read it, even after an earlier operation in the same batch added or deleted scenes.","type":"integer","minimum":1,"maximum":250},"mood":{"description":"The scene's mood. It picks the camera motion, transitions, colour and sound. One of: calm, curious, uneasy, tense, dramatic, shocking, terrifying, mysterious, solemn, triumphant, chaotic, playful.","type":"string","enum":["calm","curious","uneasy","tense","dramatic","shocking","terrifying","mysterious","solemn","triumphant","chaotic","playful"]}},"required":["op","scene","mood"],"additionalProperties":false},{"description":"Change what one scene's picture shows.","type":"object","properties":{"op":{"type":"string","const":"set_description"},"scene":{"description":"A scene number from the script you read (1 = the first scene). Numbers always mean the script as you read it, even after an earlier operation in the same batch added or deleted scenes.","type":"integer","minimum":1,"maximum":250},"text":{"description":"What the picture for this scene shows, in English (this is the picture prompt). Up to 1,000 characters.","type":"string","minLength":1,"maxLength":1000}},"required":["op","scene","text"],"additionalProperties":false},{"description":"Add a new scene. Its length is estimated from its narration.","type":"object","properties":{"op":{"type":"string","const":"add_scene"},"after":{"description":"Put the new scene after this scene number (0 = before the first scene).","type":"integer","minimum":0,"maximum":250},"narration":{"description":"What the narrator says in this scene, in the video's language. One scene holds up to about 40% of the whole narration (at most 2,000 characters).","type":"string","minLength":1,"maxLength":2000},"mood":{"description":"The scene's mood. It picks the camera motion, transitions, colour and sound. One of: calm, curious, uneasy, tense, dramatic, shocking, terrifying, mysterious, solemn, triumphant, chaotic, playful.","type":"string","enum":["calm","curious","uneasy","tense","dramatic","shocking","terrifying","mysterious","solemn","triumphant","chaotic","playful"]},"description":{"description":"What the picture shows, in English. Leave it out to picture the narration itself.","type":"string","minLength":1,"maxLength":1000}},"required":["op","after","narration"],"additionalProperties":false},{"description":"Delete one scene. A script keeps at least one scene.","type":"object","properties":{"op":{"type":"string","const":"delete_scene"},"scene":{"description":"A scene number from the script you read (1 = the first scene). Numbers always mean the script as you read it, even after an earlier operation in the same batch added or deleted scenes.","type":"integer","minimum":1,"maximum":250}},"required":["op","scene"],"additionalProperties":false},{"description":"Move one scene to another position.","type":"object","properties":{"op":{"type":"string","const":"move_scene"},"scene":{"description":"A scene number from the script you read (1 = the first scene). Numbers always mean the script as you read it, even after an earlier operation in the same batch added or deleted scenes.","type":"integer","minimum":1,"maximum":250},"to":{"description":"The position the scene moves to, counted in the scene list as it stands at this point of the batch (1 = first).","type":"integer","minimum":1,"maximum":250}},"required":["op","scene","to"],"additionalProperties":false},{"description":"Open the video with one of the script's other hook lines: it becomes the first scene's narration.","type":"object","properties":{"op":{"type":"string","const":"use_hook"},"variant":{"description":"Which of the script's other opening lines (hookVariants, 1 to 3) to use.","type":"integer","minimum":1,"maximum":3}},"required":["op","variant"],"additionalProperties":false},{"description":"Change the story title.","type":"object","properties":{"op":{"type":"string","const":"set_title"},"title":{"description":"The story title.","type":"string","minLength":1,"maxLength":200}},"required":["op","title"],"additionalProperties":false}]}}},"required":["expectedRevision","operations"],"additionalProperties":false},"example":{"expectedRevision":1,"operations":[{"op":"set_narration","scene":2,"text":"Then, one stormy night, its great lamp began to turn again."}]}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project id (from v3_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project id (from v3_projects list or create).","example":"v3_8f14e45fceea167a"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"description":"The project (see v3_projects get), with its script.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"revisions":{"type":"object","properties":{"script":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"timeline":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["script","timeline"],"additionalProperties":false},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"hookVariants":{"type":"array","items":{"type":"string"}},"totalDurationMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"narration":{"type":"string"},"mood":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"type":"string"},"durationMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"shotType":{"anyOf":[{"type":"string"},{"type":"null"}]},"transition":{"anyOf":[{"type":"string"},{"type":"null"}]},"emphasisWords":{"type":"array","items":{"type":"string"}},"soundCues":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["number","narration","mood","description","durationMs","shotType","transition","emphasisWords","soundCues"],"additionalProperties":false}}},"required":["title","hookVariants","totalDurationMs","scenes"],"additionalProperties":false},{"type":"null"}]}},"required":["id","product","title","status","stage","revisions"],"additionalProperties":{}},"revision":{"description":"The script revision after this change. Send it as expectedRevision with your next change.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"changes":{"description":"What changed, in plain words.","type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}}},"required":["project","revision","changes"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"v3_8f14e45fceea167a","product":"v3","title":"The Lighthouse Keeper","status":"script-ready","stage":"Script ready to review","progress":20,"revisions":{"script":2,"timeline":0},"credits":{"script":25,"assets":0},"links":{"app":"https://app.autoclips.app/create/cinematic-story?project=v3_8f14e45fceea167a","editor":"https://app.autoclips.app/editor/v3_8f14e45fceea167a"},"script":{"title":"The Lighthouse Keeper","hookVariants":["Nobody had climbed those stairs in forty years.","The light came on by itself.","What would you do if the sea called your name?"],"totalDurationMs":9620,"scenes":[{"number":1,"narration":"The lighthouse had been dark for forty years.","mood":"mysterious","description":"An abandoned stone lighthouse on a cliff at dusk, storm clouds gathering","durationMs":2925,"shotType":"close-up","transition":"swipe-left","emphasisWords":[],"soundCues":[]},{"number":2,"narration":"Then, one stormy night, its great lamp began to turn again.","mood":"uneasy","description":"A beam of light sweeping across a black sea from the lighthouse top","durationMs":3835,"shotType":"wide","transition":"swipe-left","emphasisWords":[],"soundCues":[]},{"number":3,"narration":"Elena rowed out alone to see who had lit it.","mood":"tense","description":"A young woman rowing a small boat through dark waves toward the lighthouse","durationMs":2860,"shotType":"wide","transition":"swipe-left","emphasisWords":[],"soundCues":[]}]}},"revision":2,"changes":["Scene 2: new narration (11 words)","Now 3 scenes, 148 characters of narration."]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/script/adjust-length":{"post":{"operationId":"v3_script_adjust_length","summary":"Ask the AI writer for all the narration about 30% shorter or longer (results vary; the answer says), keeping the scenes.","description":"An AI rewrites every scene's narration, asked for about 30% shorter or longer. How much it really changes varies (often less): the answer gives the narration length before and after, and a warning when it changed under 20%, so run it again or edit scenes by hand. The scenes, their moods, picture descriptions and other details stay as they were. Free, within the daily limit for free AI helpers. Allowed while the script is ready (status script-ready) and before the pictures are made; expectedRevision is required. If the project changes during the rewrite (for example pictures start), nothing is saved. undo brings the previous narration back.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.script.adjust_length","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_script action=adjust_length","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"direction":{"description":"shorter or longer (the writer is asked for about 30%).","type":"string","enum":["shorter","longer"]},"expectedRevision":{"description":"The script revision you read (revisions.script). Required, so a retried request never shortens or lengthens twice.","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["direction","expectedRevision"],"additionalProperties":false},"example":{"direction":"shorter","expectedRevision":2}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project id (from v3_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project id (from v3_projects list or create).","example":"v3_8f14e45fceea167a"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"description":"The project (see v3_projects get), with its script.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"revisions":{"type":"object","properties":{"script":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"timeline":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["script","timeline"],"additionalProperties":false},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"hookVariants":{"type":"array","items":{"type":"string"}},"totalDurationMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"narration":{"type":"string"},"mood":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"type":"string"},"durationMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"shotType":{"anyOf":[{"type":"string"},{"type":"null"}]},"transition":{"anyOf":[{"type":"string"},{"type":"null"}]},"emphasisWords":{"type":"array","items":{"type":"string"}},"soundCues":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["number","narration","mood","description","durationMs","shotType","transition","emphasisWords","soundCues"],"additionalProperties":false}}},"required":["title","hookVariants","totalDurationMs","scenes"],"additionalProperties":false},{"type":"null"}]}},"required":["id","product","title","status","stage","revisions"],"additionalProperties":{}},"revision":{"description":"The script revision after this change. Send it as expectedRevision with your next change.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"narrationCharacters":{"type":"object","properties":{"before":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"after":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["before","after"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"}}},"required":["project","revision","narrationCharacters"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/script/generate":{"post":{"operationId":"v3_script_generate","summary":"Write the project's script from its topic or story. Costs credits once per project; a long video is written in the background.","description":"Writes the scene-by-scene script from the topic or story saved on the project, using the project's length, writer (standard or max), shape, voice model and language. A story opens with the AI hook intro unless hookIntro is false; a topic gets a complete ending unless cliffhanger is true (each defaults to the project's setting). series writes the next part of a series with this project's own settings (a new draft has the default ones, not the previous part's); v3_projects quick_create with series makes a next part that keeps the previous part's settings. The price is the script part of the video (25 credits a minute with the standard writer, 50 with max, times your plan's multiplier). If the saved settings cost more by the time it runs than the price you approved, nothing runs and the answer is a conflict (price_changed): ask for a new price. A project's script is paid once: writing it again costs nothing, up to 3 times per project (each uses one of the day's free AI helper uses), and is refused when the length or writer now costs more than was paid. A pasted story is narrated word for word, so a story too long for the project's length raises the length (up to your plan's longest), and the price with it. A story written as a script is narrated without most of its formatting: timestamps, scene headings (\"Scene 2: …\", \"INT. …\"), camera and edit notes (\"Wide shot:\", \"Cut to:\"), sound and music note lines (\"SFX: …\") and speaker names before a colon (\"AIKO: …\") are left out, and so is an acting note in brackets such as (whispering) on its own line, after the name, or opening a line in three words or fewer (a voice model that performs audio tags may get it as a tag). Still read aloud: a name on a line of its own, a lone \"Name:\" in plain prose, and a note inside a sentence or longer than three words. Its length is what is read aloud. A short video's script comes back in the same answer once it is written, which takes about half a minute (the call waits for it; an app that stops waiting sooner should read the project with v3_projects get before asking again). A longer one (usually 3 minutes and up) is written in the background: the answer is then a job to follow with autoclips_jobs get, and the script shows in v3_projects get once the job has succeeded. Allowed while the project is a draft, has a script ready, or stopped before its pictures were made. A project that already has a script needs replace: true; undo brings the replaced script back.\n\n**Permissions:** edit, spend.\n**Cost:** Costs credits. The price is worked out on our side and is an upper bound: you are never charged more. Send `max_credits` (the most credits you accept) or a `quote_token` from POST /api/v1/quotes (or from a 402 answer) in the body. Without either, nothing runs and you get 402 with the price and a quote_token.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit","spend"]}],"x-autoclips-operation":"v3.script.generate","x-autoclips-scopes":["edit","spend"],"x-autoclips-cost":"paid","x-autoclips-mcp":"v3_script action=generate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"replace":{"description":"Must be true when the project already has a script: the new script replaces it (undo brings it back).","type":"boolean"},"hookIntro":{"description":"Only for projects made from a story (pasted text or a Reddit post): open with one original hook line, then the story as it is written (a script without its formatting). Leave it out to keep the project's setting (on unless it was turned off, as in the app).","type":"boolean"},"cliffhanger":{"description":"Only for projects written from a topic: stop the story at the big reveal, so viewers want the next part. Leave it out to keep the project's setting (off unless it was turned on, as in the app: the story gets a complete ending).","type":"boolean"},"series":{"description":"Only for projects written from a topic: write this as the next part of a series, carrying on from the previous part, with its characters, places and objects. It carries on the story only: this project keeps its own settings, and a draft made with v3_projects create starts from the default settings (length, shape, language, look, featured characters), not the previous part's. For a next part that keeps the previous part's settings, as the app's \"Create Part N\" does, use v3_projects quick_create with series instead.","type":"object","properties":{"part":{"description":"Which part this is (2 to 20). Leave it out for the part after the previous one, as the app's \"Create Part N\" button does.","type":"integer","minimum":2,"maximum":20},"previousProjectId":{"description":"The V3 project of the previous part. It must be yours and have a script.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"cliffhanger":{"description":"The same as cliffhanger (kept for older callers). Default: the project's setting, off unless it was turned on.","type":"boolean"}},"required":["previousProjectId"],"additionalProperties":false},"max_credits":{"type":"integer","minimum":0,"description":"The most credits you accept. If the price is higher, nothing runs and you get 402 with the price. Send this or quote_token."},"quote_token":{"type":"string","description":"A quote_token from POST /api/v1/quotes (or from a 402 answer), to run at exactly that price. Works once, for 10 minutes."}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project id (from v3_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project id (from v3_projects list or create).","example":"v3_8f14e45fceea167a"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"description":"The project (see v3_projects get), with its script.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"revisions":{"type":"object","properties":{"script":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"timeline":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["script","timeline"],"additionalProperties":false},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"hookVariants":{"type":"array","items":{"type":"string"}},"totalDurationMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"narration":{"type":"string"},"mood":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"type":"string"},"durationMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"shotType":{"anyOf":[{"type":"string"},{"type":"null"}]},"transition":{"anyOf":[{"type":"string"},{"type":"null"}]},"emphasisWords":{"type":"array","items":{"type":"string"}},"soundCues":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["number","narration","mood","description","durationMs","shotType","transition","emphasisWords","soundCues"],"additionalProperties":false}}},"required":["title","hookVariants","totalDurationMs","scenes"],"additionalProperties":false},{"type":"null"}]}},"required":["id","product","title","status","stage","revisions"],"additionalProperties":{}},"revision":{"description":"The script revision after this change. Send it as expectedRevision with your next change.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"job":{"description":"Present when the script is being written in the background (longer videos). Follow it with autoclips_jobs get.","type":"object","properties":{"id":{"description":"The job id (job_…).","type":"string"},"product":{"description":"Which AutoClips product runs the job.","type":"string","enum":["shared","v3","ce","studio","stickman","fruit"]},"kind":{"description":"What the job does, for example \"v3.render\".","type":"string"},"resource":{"description":"The project or item the job works on.","type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"status":{"description":"queued, running, succeeded, failed or canceled. The last three are final.","type":"string","enum":["queued","running","succeeded","failed","canceled"]},"step":{"description":"The step it is on, in plain words, when known.","anyOf":[{"type":"string"},{"type":"null"}]},"progress":{"description":"Percent done, when known. It never goes down.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"result":{"description":"What the job made (for example a video link), once it succeeded.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"description":"Why it failed or was canceled, in plain words. The code \"superseded\" means a newer run of the same project replaced this one; \"stopped_responding\" means it went on far too long and was marked as failed; \"stalled\" means the work itself stopped (nothing moved for much longer than a working run ever stays quiet). The project says what can be done next.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"description":"Wait this long before checking again. Null once the job is finished.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"usualSeconds":{"description":"About how long this kind of job usually takes from start to finish, in seconds, when known. A guide, not a promise.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stalled":{"description":"Present while an unfinished job has shown no progress for much longer than usual: it may have stopped. Tell the user instead of waiting in silence.","type":"object","properties":{"since":{"description":"When anything last moved (ISO 8601, UTC).","type":"string"},"message":{"description":"How long nothing has moved, and what to do.","type":"string"}},"required":["since","message"],"additionalProperties":false},"note":{"description":"Present when the status shown was not confirmed just now: status_check_failed (the check failed or ran out of time) or not_rechecked (a list did not get to it). The job shown is the last known state.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","product","kind","resource","status","step","progress","result","error","createdAt","updatedAt","finishedAt","poll_after_seconds"],"additionalProperties":false},"warnings":{"description":"Present when something needs your attention, for example the project changed while the script was being written, so the new script is not a new revision.","type":"array","items":{"type":"string"}}},"required":["project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"creditsCharged":{"type":"integer","minimum":0,"description":"Credits this request charged. 0 on a replay (meta.idempotentReplay): then originallyCharged says what the first request charged."},"creditsApproved":{"type":"integer","minimum":0,"description":"Credits you approved for work that is charged as it runs, not a charge yet. 0 on a replay: then originallyApproved says what the first request approved."},"originallyCharged":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key charged. The replay itself charged nothing."},"originallyApproved":{"type":"integer","minimum":0,"description":"On a replay only: what the first request with this Idempotency-Key approved. The replay itself approved nothing."},"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"v3_8f14e45fceea167a","product":"v3","title":"The Lighthouse Keeper","status":"script-ready","stage":"Script ready to review","progress":20,"revisions":{"script":1,"timeline":0},"credits":{"script":25,"assets":0},"links":{"app":"https://app.autoclips.app/create/cinematic-story?project=v3_8f14e45fceea167a","editor":"https://app.autoclips.app/editor/v3_8f14e45fceea167a"},"script":{"title":"The Lighthouse Keeper","hookVariants":["Nobody had climbed those stairs in forty years.","The light came on by itself.","What would you do if the sea called your name?"],"totalDurationMs":8385,"scenes":[{"number":1,"narration":"The lighthouse had been dark for forty years.","mood":"mysterious","description":"An abandoned stone lighthouse on a cliff at dusk, storm clouds gathering","durationMs":2925,"shotType":"close-up","transition":"swipe-left","emphasisWords":[],"soundCues":[]},{"number":2,"narration":"Then, one night, its lamp began to turn.","mood":"uneasy","description":"A beam of light sweeping across a black sea from the lighthouse top","durationMs":2600,"shotType":"wide","transition":"swipe-left","emphasisWords":[],"soundCues":[]},{"number":3,"narration":"Elena rowed out alone to see who had lit it.","mood":"tense","description":"A young woman rowing a small boat through dark waves toward the lighthouse","durationMs":2860,"shotType":"wide","transition":"swipe-left","emphasisWords":[],"soundCues":[]}]}},"revision":1}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/script/undo":{"post":{"operationId":"v3_script_undo","summary":"Bring back the script as it was before the last change. Up to 5 steps back.","description":"Restores the script as it was before the last edit, re-write or length change (scenes, title, other hook lines and sound theme), saved as a new revision. Each undo goes one version further back, up to 5 (fewer for very long scripts, whose versions are large); an undo cannot itself be undone. Send expectedRevision (the revision you read). Allowed until the pictures are made.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.script.undo","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_script action=undo","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedRevision":{"description":"The script revision you read (revisions.script).","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["expectedRevision"],"additionalProperties":false},"example":{"expectedRevision":2}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project id (from v3_projects list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project id (from v3_projects list or create).","example":"v3_8f14e45fceea167a"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"description":"The project (see v3_projects get), with its script.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"revisions":{"type":"object","properties":{"script":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"timeline":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["script","timeline"],"additionalProperties":false},"script":{"anyOf":[{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"hookVariants":{"type":"array","items":{"type":"string"}},"totalDurationMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"narration":{"type":"string"},"mood":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"type":"string"},"durationMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"shotType":{"anyOf":[{"type":"string"},{"type":"null"}]},"transition":{"anyOf":[{"type":"string"},{"type":"null"}]},"emphasisWords":{"type":"array","items":{"type":"string"}},"soundCues":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["number","narration","mood","description","durationMs","shotType","transition","emphasisWords","soundCues"],"additionalProperties":false}}},"required":["title","hookVariants","totalDurationMs","scenes"],"additionalProperties":false},{"type":"null"}]}},"required":["id","product","title","status","stage","revisions"],"additionalProperties":{}},"revision":{"description":"The script revision after this change. Send it as expectedRevision with your next change.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"changes":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}}},"required":["project","revision","changes"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"v3_8f14e45fceea167a","product":"v3","title":"The Lighthouse Keeper","status":"script-ready","stage":"Script ready to review","progress":20,"revisions":{"script":3,"timeline":0},"credits":{"script":25,"assets":0},"links":{"app":"https://app.autoclips.app/create/cinematic-story?project=v3_8f14e45fceea167a","editor":"https://app.autoclips.app/editor/v3_8f14e45fceea167a"},"script":{"title":"The Lighthouse Keeper","hookVariants":["Nobody had climbed those stairs in forty years.","The light came on by itself.","What would you do if the sea called your name?"],"totalDurationMs":8385,"scenes":[{"number":1,"narration":"The lighthouse had been dark for forty years.","mood":"mysterious","description":"An abandoned stone lighthouse on a cliff at dusk, storm clouds gathering","durationMs":2925,"shotType":"close-up","transition":"swipe-left","emphasisWords":[],"soundCues":[]},{"number":2,"narration":"Then, one night, its lamp began to turn.","mood":"uneasy","description":"A beam of light sweeping across a black sea from the lighthouse top","durationMs":2600,"shotType":"wide","transition":"swipe-left","emphasisWords":[],"soundCues":[]},{"number":3,"narration":"Elena rowed out alone to see who had lit it.","mood":"tense","description":"A young woman rowing a small boat through dark waves toward the lighthouse","durationMs":2860,"shotType":"wide","transition":"swipe-left","emphasisWords":[],"soundCues":[]}]}},"revision":3,"changes":["Back to the script of revision 1 (3 scenes). 0 earlier versions left to undo."]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/seo":{"post":{"operationId":"v3_seo_generate","summary":"Write a title, description, tags and hashtags for posting the video. Free, limited per day.","description":"Writes a post title, a description, search tags and hashtags from the project's script, in the project's language, and saves them on the project (replacing earlier ones). Free, but it counts toward the daily limit for free AI helpers. A finished render writes these by itself too. Not while Quick Create is still making the project.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.seo.generate","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_production action=seo","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project id (from v3 list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project id (from v3 list or create).","example":"6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"seo":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"hashtags":{"type":"array","items":{"type":"string"}}},"required":["title","description","tags","hashtags"],"additionalProperties":false},"project":{"description":"The project after this step, in the same shape as reading the project.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"progress":{"type":"number"},"problem":{"anyOf":[{"type":"string"},{"type":"null"}]},"video":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"renderedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","thumbnailUrl","renderedAt"],"additionalProperties":false},{"type":"null"}]},"render":{"type":"object","properties":{"status":{"type":"string"},"progress":{"type":"number"}},"required":["status","progress"],"additionalProperties":false},"credits":{"type":"object","properties":{"script":{"type":"number"},"assets":{"type":"number"},"assetsLengthSeconds":{"description":"The length the pictures, voice and music were charged for: the script's real length, then the recording's once it is made.","anyOf":[{"type":"number"},{"type":"null"}]},"returnedForShorterVideo":{"description":"Credits given back because the recording ran shorter than the length charged for.","type":"number"}},"required":["script","assets"],"additionalProperties":{}},"links":{"type":"object","properties":{"app":{"type":"string"},"editor":{"type":"string"}},"required":["app","editor"],"additionalProperties":false}},"required":["id","product","title","status","stage","progress","problem","video","render","credits","links"],"additionalProperties":{}}},"required":["seo","project"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"seo":{"title":"The lighthouse keepers who vanished","description":"Three men, one island, no trace.","tags":["mystery","lighthouse","true story"],"hashtags":["#Mystery","#TrueStory"]},"project":{"id":"6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40","product":"v3","title":"The Keeper of Flannan Isle","status":"completed","stage":"Video ready","progress":100,"problem":null,"createdAt":"2026-09-28T09:40:00.000Z","updatedAt":"2026-09-28T10:02:00.000Z","settings":{"category":"horror","durationSeconds":60,"aspectRatio":"9:16","imageModel":"grokImagine","style":"realistic-4k","secondsPerImage":3,"scriptMode":"max","sfxMode":"standard","animation":"none","animationModel":"autoclips1","directVideo":false,"consistency":false,"language":"en","voiceId":null,"voiceModel":"eleven_v4","captions":true,"motionText":false,"subjectWobble":false,"hookIntro":null,"cliffhanger":false,"delivery":"narrator","speakModel":null,"likenessRightsConfirmed":false,"watermarkType":"none","watermarkText":null,"watermarkTextColor":"#FFFFFF","watermarkBackgroundColor":"#000000","watermarkBackgroundOpacity":0.5,"watermarkImageOpacity":0.7,"watermarkVerticalPosition":85,"watermarkHorizontalPosition":85,"watermarkScale":1,"watermarkStartSeconds":0,"watermarkEndSeconds":0,"outroId":null},"series":{"part":1,"previousProjectId":null},"input":{"mode":"topic","topic":"The lighthouse keeper who vanished","storyTitle":null,"hasStoryText":false,"redditUrl":null},"counts":{"scenes":3,"pictures":0,"picturesReady":0},"video":{"url":"https://media.autoclips.app/clips/v3-videos/example.mp4","thumbnailUrl":null,"renderedAt":"2026-09-28T10:02:00.000Z"},"render":{"status":"done","progress":100},"pipeline":null,"revisions":{"script":0,"timeline":0},"credits":{"script":50,"assets":487,"assetsLengthSeconds":57.54,"returnedForShorterVideo":0},"isDemo":false,"links":{"app":"https://app.autoclips.app/create/cinematic-story?project=6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40","editor":"https://app.autoclips.app/editor/6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40"}}}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/projects/{projectId}/timeline/build":{"post":{"operationId":"v3_timeline_build","summary":"Put the finished pictures, voice and music together into a timeline, ready to render. Free.","description":"Builds the project's timeline (scene order, timing, captions, sound effects and music) from its finished pictures and voice. Free. It answers once the timeline is built, which takes about half a minute for a 60-second video of stills; the first build of a video with moving scenes can take a minute or more, because the sound of each clip is checked. Render does this by itself when needed, so you only need this to look at or edit the timeline before rendering. A timeline that is already built from the current pictures is kept as it is (building again would drop edits), and the answer says so; one built before the pictures were made again is replaced.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.timeline.build","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_production action=build_timeline","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"description":"The V3 project id (from v3 list or create).","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"description":"The V3 project id (from v3 list or create).","example":"6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project":{"description":"The project after this step, in the same shape as reading the project.","type":"object","properties":{"id":{"type":"string"},"product":{"type":"string","const":"v3"},"title":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"progress":{"type":"number"},"problem":{"anyOf":[{"type":"string"},{"type":"null"}]},"video":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"renderedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","thumbnailUrl","renderedAt"],"additionalProperties":false},{"type":"null"}]},"render":{"type":"object","properties":{"status":{"type":"string"},"progress":{"type":"number"}},"required":["status","progress"],"additionalProperties":false},"credits":{"type":"object","properties":{"script":{"type":"number"},"assets":{"type":"number"},"assetsLengthSeconds":{"description":"The length the pictures, voice and music were charged for: the script's real length, then the recording's once it is made.","anyOf":[{"type":"number"},{"type":"null"}]},"returnedForShorterVideo":{"description":"Credits given back because the recording ran shorter than the length charged for.","type":"number"}},"required":["script","assets"],"additionalProperties":{}},"links":{"type":"object","properties":{"app":{"type":"string"},"editor":{"type":"string"}},"required":["app","editor"],"additionalProperties":false}},"required":["id","product","title","status","stage","progress","problem","video","render","credits","links"],"additionalProperties":{}},"built":{"description":"True when the timeline was built now; false when it already existed.","type":"boolean"},"message":{"type":"string"}},"required":["project","built","message"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"project":{"id":"6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40","product":"v3","title":"The Keeper of Flannan Isle","status":"edl-ready","stage":"Ready to render","progress":80,"problem":null,"createdAt":"2026-09-28T09:40:00.000Z","updatedAt":"2026-09-28T10:02:00.000Z","settings":{"category":"horror","durationSeconds":60,"aspectRatio":"9:16","imageModel":"grokImagine","style":"realistic-4k","secondsPerImage":3,"scriptMode":"max","sfxMode":"standard","animation":"none","animationModel":"autoclips1","directVideo":false,"consistency":false,"language":"en","voiceId":null,"voiceModel":"eleven_v4","captions":true,"motionText":false,"subjectWobble":false,"hookIntro":null,"cliffhanger":false,"delivery":"narrator","speakModel":null,"likenessRightsConfirmed":false,"watermarkType":"none","watermarkText":null,"watermarkTextColor":"#FFFFFF","watermarkBackgroundColor":"#000000","watermarkBackgroundOpacity":0.5,"watermarkImageOpacity":0.7,"watermarkVerticalPosition":85,"watermarkHorizontalPosition":85,"watermarkScale":1,"watermarkStartSeconds":0,"watermarkEndSeconds":0,"outroId":null},"series":{"part":1,"previousProjectId":null},"input":{"mode":"topic","topic":"The lighthouse keeper who vanished","storyTitle":null,"hasStoryText":false,"redditUrl":null},"counts":{"scenes":3,"pictures":0,"picturesReady":0},"video":null,"render":{"status":"idle","progress":0},"pipeline":null,"revisions":{"script":0,"timeline":0},"credits":{"script":50,"assets":487,"assetsLengthSeconds":57.54,"returnedForShorterVideo":0},"isDemo":false,"links":{"app":"https://app.autoclips.app/create/cinematic-story?project=6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40","editor":"https://app.autoclips.app/editor/6f1c2a9e-4b7d-4e21-9a3c-5d8e7f1b2c40"}},"built":true,"message":"The timeline is built. Render the video with render (free)."}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/stories/import":{"post":{"operationId":"v3_stories_import","summary":"Read a Reddit post and return its title and text, ready to use as a V3 story.","description":"Fetches a public Reddit text post and returns its title and full text. Nothing is saved: create a project with the text as its story (v3_projects create), then write the script. Only reddit.com post links (…/r/<sub>/comments/<id>/…) work; link and picture posts have no text to use.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"v3.stories.import","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_script action=import_story","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"description":"The Reddit post link (https://www.reddit.com/r/<subreddit>/comments/<id>/…).","type":"string","maxLength":2048,"allOf":[{"pattern":"^https:\\/\\/[^\\s]+$"},{"pattern":"^https:\\/\\/(?:www\\.|old\\.|new\\.)?reddit\\.com\\/r\\/[A-Za-z0-9_]{2,40}\\/comments\\/[A-Za-z0-9]{2,16}(?:[/?#][^\\s]*)?$"}]}},"required":["url"],"additionalProperties":false},"example":{"url":"https://www.reddit.com/r/nosleep/comments/1abc2de/the_lighthouse_keeper/"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"title":{"type":"string"},"text":{"description":"The post's full text.","type":"string"},"words":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"author":{"anyOf":[{"type":"string"},{"type":"null"}]},"subreddit":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"type":"string"}},"required":["title","text","words","author","subreddit","sourceUrl"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"title":"The lighthouse keeper","text":"I took the job because nobody else wanted it...","words":9,"author":"u/storyteller","subreddit":"r/nosleep","sourceUrl":"https://www.reddit.com/r/nosleep/comments/1abc2de/the_lighthouse_keeper/"}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/topics/classify":{"post":{"operationId":"v3_topics_classify","summary":"Suggest the best V3 category for a topic (horror, history, space, …) with a confidence from 0 to 1.","description":"An AI picks the V3 category that fits a topic best. Use it to fill the category when creating a project. When it is unsure it answers \"general\" with confidence 0. Free, within the daily limit for free AI helpers.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"v3.topics.classify","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_script action=classify_topic","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"topic":{"description":"The video topic, 3 to 500 characters.","type":"string","minLength":3,"maxLength":500}},"required":["topic"],"additionalProperties":false},"example":{"topic":"A night shift guard hears footsteps on the empty floor above"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"category":{"description":"A category id from the V3 options.","type":"string"},"label":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1}},"required":["category","label","confidence"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"category":"horror","label":"Horror & Dark Facts","confidence":0.92}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/topics/ideas":{"get":{"operationId":"v3_topics_ideas","summary":"Today's topic ideas for V3 videos, each with its category. Optionally only one category.","description":"Lists today's topic ideas (made fresh each day from what is trending on AutoClips; yesterday's when today's are not ready yet). Each has a title, a category and a short description. Free.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"v3.topics.ideas","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"v3_script action=topic_ideas","parameters":[{"name":"category","in":"query","required":false,"schema":{"description":"Only ideas in this category.","type":"string","enum":["horror","science","history","crime","space","nature","travel","food","technology","psychology","mythology","general"]},"description":"Only ideas in this category.","example":"horror"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"date":{"description":"The day the ideas are for (YYYY-MM-DD).","anyOf":[{"type":"string"},{"type":"null"}]},"ideas":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"}},"required":["title","category","description"],"additionalProperties":false}}},"required":["date","ideas"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"date":"2026-09-28","ideas":[{"title":"The ship that sailed itself for 30 years","category":"history","description":"A ghost ship found drifting with no crew and dinner still on the table."}]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/voices/clone":{"post":{"operationId":"v3_voices_clone","summary":"Clone a voice from a recording in your media library, for your V3 characters to speak with.","description":"Makes a new voice from a sound recording already in your media library: at least 5 seconds of one person speaking clearly, with no music or background noise (only the first 25 seconds are used). Bring the recording in first with autoclips_media (upload_link or import_url), then send its media id and a name. The new voice is for V3 characters: give it to a character with v3_characters update (voice = the new voiceId or its name). It cannot narrate a video: to clone a narrator voice, use clone_narrator. Free, but your plan sets how many cloned voices you can keep, and free plans cannot clone. Delete one with autoclips_voices delete to make room. Cloning takes up to a minute. If a call seems lost, calling clone again with the same recording and name within 10 minutes answers the voice already made (alreadyMade: true) instead of making a second one. Over REST, an Idempotency-Key does the same.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["AutoClips V3 (cinematic stories)"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"v3.voices.clone","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_voices action=clone","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mediaId":{"description":"A sound recording in your media library (autoclips_media list, upload_link or import_url): at least 5 seconds of one person speaking clearly, up to 50 MB. Only the first 25 seconds are used.","type":"string","pattern":"^[a-fA-F0-9]{24}$"},"name":{"description":"What to call the voice (1 to 60 characters), for example \"Grandpa Joe\". You can pick it by this name later.","type":"string","minLength":1,"maxLength":60,"pattern":"^[^\\u0000-\\u001f\\u007f\\u202A-\\u202E\\u2066-\\u2069]+$"}},"required":["mediaId","name"],"additionalProperties":false},"example":{"mediaId":"66f7c0ffee00000000000004","name":"Grandpa Joe"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"voice":{"description":"The voice. Use its voiceId (or name) as a V3 character's voice.","type":"object","properties":{"voiceId":{"description":"Use this id (or the name) wherever a voice is asked for.","type":"string"},"name":{"type":"string"},"source":{"description":"library = an AutoClips voice; cloned = one of your own cloned voices.","type":"string","enum":["library","cloned"]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"accent":{"anyOf":[{"type":"string"},{"type":"null"}]},"languages":{"description":"The languages the voice library lists for this voice, as codes (\"es\" for Spanish); empty when it lists none. Search by a language's name to find them.","type":"array","items":{"type":"string"}},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"previewUrl":{"description":"A short sample to listen to, when there is one.","anyOf":[{"type":"string"},{"type":"null"}]},"recommended":{"description":"One of the voices AutoClips picked for narration.","type":"boolean"},"uses":{"description":"narrator = can narrate a V3 video; character = can be a V3 character's voice.","type":"array","items":{"type":"string","enum":["narrator","character"]}},"createdAt":{"description":"When you cloned it (your own voices only).","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["voiceId","name","source","gender","accent","description","previewUrl","recommended","uses","createdAt"],"additionalProperties":false},"alreadyMade":{"description":"True when this recording was already cloned under this name in the last 10 minutes: that voice is returned and nothing new was made.","type":"boolean"}},"required":["voice","alreadyMade"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"voice":{"voiceId":"3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f","name":"Grandpa Joe","source":"cloned","gender":null,"accent":null,"description":"Your cloned voice, for character clips.","previewUrl":null,"recommended":false,"uses":["character"],"createdAt":"2026-09-28T10:15:00.000Z"},"alreadyMade":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos":{"get":{"operationId":"shared_videos_list","summary":"List your videos from every AutoClips format, newest first: what My Videos shows.","description":"Every format in one list (Character Explainer, V3, Studio 2.0, Stickman, Fruit Stories, UGC Ads, the Video Editor, …), newest first, with each video's file once it is finished. Filter with source for one kind, and finished for complete videos only. Pages of up to 50; ask for the next page while hasMore is true.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.videos.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_videos action=list","parameters":[{"name":"source","in":"query","required":false,"schema":{"description":"Only this kind of video. Default: all.","type":"string","enum":["all","faceless","character","studio","studio-v2","cinematic","quiz","text-story","talking-objects","fruit-stories","time-travel","claymation","miniature","stickman","ugc-ads","upscaler","editor"]},"description":"Only this kind of video. Default: all.","example":"character"},{"name":"finished","in":"query","required":false,"schema":{"description":"Only finished videos (status complete with a file). Default: false.","type":"boolean"},"description":"Only finished videos (status complete with a file). Default: false.","example":true},{"name":"page","in":"query","required":false,"schema":{"description":"Page, counting from 1 (default 1).","type":"integer","minimum":1,"maximum":50},"description":"Page, counting from 1 (default 1)."},{"name":"limit","in":"query","required":false,"schema":{"description":"Videos per page (default 20).","type":"integer","minimum":1,"maximum":50},"description":"Videos per page (default 20).","example":10}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"source":{"description":"The kind of video (character, cinematic, studio-v2, editor, …). autoclips_editor import_video takes it with videoId.","type":"string"},"videoId":{"description":"The video's id within its kind.","type":"string"},"title":{"type":"string"},"status":{"description":"complete when the video is finished; processing or error otherwise.","type":"string"},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"description":"The finished video file, once complete.","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","videoId","title","status","durationSeconds","thumbnailUrl","videoUrl","createdAt"],"additionalProperties":false}},"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"type":"boolean"}},"required":["items","page","hasMore"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"items":[{"source":"character","videoId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","title":"Why cats knock things off tables","status":"complete","durationSeconds":31.2,"thumbnailUrl":"https://media.autoclips.app/generated-images/cats-poster.jpg","videoUrl":"https://media.autoclips.app/videos/ce/cats.mp4","createdAt":"2026-10-20T09:12:00.000Z"}],"page":1,"hasMore":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos/post-status":{"get":{"operationId":"shared_videos_post_status","summary":"Check whether posts made with publish are live yet, with a link to each live post.","description":"publish says \"posted\" when the platform accepts a post; the platform shows it 30 seconds to a few minutes later. Pass the postId values publish returned (up to 12). Each answer is live (with its link when the platform sent one), going_up (accepted in the last 15 minutes, not live yet), waiting (accepted longer ago, the platform has not confirmed it) or failed (with the platform's reason). A post id this account did not make, or one this cannot follow, is listed under unknown. Free.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.videos.post_status","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_publish action=post_status","parameters":[{"name":"postIds","in":"query","required":true,"schema":{"description":"The postId values from publish results.","minItems":1,"maxItems":12,"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"}},"description":"The postId values from publish results.","example":["47e3b5fd-84bb-4c39-9424-c5db48a69938"]}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"posts":{"type":"array","items":{"type":"object","properties":{"postId":{"type":"string"},"state":{"type":"string","enum":["live","going_up","waiting","failed"]},"url":{"description":"The live post, when the platform sent its link.","anyOf":[{"type":"string"},{"type":"null"}]},"error":{"description":"Why the platform turned it down (failed only).","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["postId","state","url","error"],"additionalProperties":false}},"unknown":{"description":"Ids with no post on this account that can be followed.","type":"array","items":{"type":"string"}}},"required":["posts","unknown"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"posts":[{"postId":"47e3b5fd-84bb-4c39-9424-c5db48a69938","state":"live","url":"https://www.tiktok.com/@lighthousetales/video/7696486103242509581","error":null}],"unknown":[]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos/publish":{"post":{"operationId":"shared_videos_publish","summary":"Post a finished video (V3, Studio 2.0, Character Explainer, Stickman or Fruit) to connected accounts. Asks first; it cannot be undone.","description":"Posts one finished video of yours to the accounts you name (ids from accounts; one per platform), right away, with the app's own posting code. The caption comes from the video: a Studio 2.0 film uses the Publish step's copy for that cut (or its title and logline), a V3 story, a Character Explainer video, a Stickman video and a Fruit or Animal story their title, description and hashtags. title, description and hashtags replace them for every account. X and Snapchat captions are shortened to fit; at most 5 hashtags are posted. A Stickman Story part posted here is filed with the part, so its series counts the comment vote from these posts (stickman_series count_votes), as it does for a post from the app. Posting cannot be undone. In an AI app it first answers with a preview (the video, each account, the exact caption) and a confirm_token; over REST the request itself is the instruction, and POST /videos/publish/preview shows the same preview without posting. For a Studio 2.0 film the preview's notes also say how many moments the free Review check still flags, as the app does before it posts; the approval covers them, and they never stop the post. Never twice: an account that already has this video, or may have it (in the last 30 days through the API, posted by the app itself when the video finished or by the automation that made it, a post that got no clear answer, or in the Studio film's publish history), is refused unless again is true, and the same request sent again (same Idempotency-Key) answers from its record instead of posting. An edited Character Explainer version is a video of its own: the posts of the one it was edited from are a note in the preview. Each account gets its own result in plain words (outcome posted, not_posted, or not_sure when a platform did not answer clearly and the post may be live); the call succeeds when at least one post went out. Needs a paid monthly or yearly plan; counts one per account toward the daily limit of posts. Free.\n\n**Permissions:** publish.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["publish"]}],"x-autoclips-operation":"shared.videos.publish","x-autoclips-scopes":["publish"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_publish action=publish","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product":{"description":"Which kind of video: v3 (a V3 cinematic story), studio (a Studio 2.0 film), ce (a Character Explainer video), stickman (a Stickman video or Story part) or fruit (a Fruit AI or Animal story, or a series part).","type":"string","enum":["v3","studio","ce","stickman","fruit"]},"projectId":{"description":"The project id: a V3 project id, a Studio 2.0 project id, a Character Explainer video (session) id, a Stickman video id, or a Fruit story id.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"videoId":{"description":"Studio 2.0 only: which finished cut to post (an id from studio_projects get with include videos). Leave it out to post the cut selected in the app.","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"accountIds":{"description":"The accounts to post to, one per platform at most (ids from the accounts action).","minItems":1,"maxItems":6,"type":"array","items":{"description":"A connected account id from the accounts action.","type":"string","pattern":"^[a-f0-9]{24}$"}},"title":{"description":"Use this title instead of the video's own (YouTube shows it as the title; other platforms put it above the caption).","type":"string","minLength":1,"maxLength":100},"description":{"description":"Use this caption text instead of the video's own. X and Snapchat get it shortened to fit.","type":"string","minLength":1,"maxLength":2000},"hashtags":{"description":"Use these hashtags instead of the video's own. At most 5 are posted. An empty list posts none.","maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":60,"pattern":"^#?[^\\s#,]+$"}},"youtubePrivacy":{"description":"YouTube visibility. Default: public.","type":"string","enum":["public","unlisted","private"]},"youtubeCategoryId":{"description":"YouTube category: 2 Autos & Vehicles, 23 Comedy, 27 Education, 24 Entertainment, 1 Film & Animation, 20 Gaming, 26 Howto & Style, 10 Music, 25 News & Politics, 29 Nonprofits & Activism, 22 People & Blogs, 15 Pets & Animals, 28 Science & Technology, 17 Sports, 19 Travel & Events. Default: 22 (People & Blogs).","type":"string","enum":["1","2","10","15","17","19","20","22","23","24","25","26","27","28","29"]},"aiDisclosure":{"description":"Label the post as AI-made where the platform supports it (YouTube, TikTok). Default: true.","type":"boolean"},"coverMediaId":{"description":"A picture from your media library (autoclips_media) to post as the thumbnail of this post only, in place of the video's own cover (autoclips_covers). YouTube, TikTok, Instagram and Facebook show it; X and Snapchat show their own frame. Kept as it is, saved as a JPEG of at most 2 MB.","type":"string","pattern":"^[a-fA-F0-9]{24}$"},"again":{"description":"true to post to an account that already has this video, or may have it (posted in the last 30 days through the API, posted by the app itself when the video finished or by the automation that made it, in the Studio film's publish history, or a post that got no clear answer). Leave it out otherwise.","type":"boolean"}},"required":["product","projectId","accountIds"],"additionalProperties":false},"example":{"product":"v3","projectId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","accountIds":["66f1a2b3c4d5e6f708192a3b","66f1a2b3c4d5e6f708192a3c"],"youtubePrivacy":"unlisted"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runId":{"description":"This post request's record.","type":"string"},"posted":{"description":"How many accounts the video went out to.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"description":"How many accounts it surely did not go out to.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"notSure":{"description":"How many accounts did not answer clearly: the post may be live there.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"video":{"type":"object","properties":{"product":{"type":"string","enum":["v3","studio","ce","stickman","fruit"]},"projectId":{"type":"string"},"videoId":{"description":"Studio 2.0: the cut that is posted.","anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"url":{"description":"The video that is posted.","type":"string"}},"required":["product","projectId","videoId","title","url"],"additionalProperties":false},"results":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string","enum":["youtube","tiktok","instagram","facebook","twitter","snapchat"]},"platformName":{"type":"string"},"account":{"type":"string"},"posted":{"type":"boolean"},"outcome":{"description":"posted; not_posted: the platform turned it down, so it did not go out; not_sure: no answer said it was turned down, so the post may be live (check the account; posting there again needs again: true).","type":"string","enum":["posted","not_posted","not_sure"]},"postId":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"description":"What happened, in plain words.","type":"string"}},"required":["accountId","platform","platformName","account","posted","outcome","postId","message"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}},"repeat":{"description":"true when this answer is the record of the same request, which already ran: nothing new was posted.","type":"boolean"}},"required":["runId","posted","failed","notSure","video","results","warnings","repeat"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"runId":"pub_3f9a0c1b2d4e5f60718293a4b5c6d7e8","posted":2,"failed":0,"notSure":0,"video":{"product":"v3","projectId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","videoId":null,"title":"The lighthouse keeper","url":"https://media.autoclips.app/videos/v3/lighthouse.mp4"},"results":[{"accountId":"66f1a2b3c4d5e6f708192a3b","platform":"tiktok","platformName":"TikTok","account":"@lighthousetales","posted":true,"outcome":"posted","postId":"66f9b1c2d3e4f5a6b7c8d9e0","message":"Posted to TikTok (@lighthousetales)."},{"accountId":"66f1a2b3c4d5e6f708192a3c","platform":"youtube","platformName":"YouTube","account":"Lighthouse Tales","posted":true,"outcome":"posted","postId":"66f9b1c2d3e4f5a6b7c8d9e1","message":"Posted to YouTube (Lighthouse Tales)."}],"warnings":[],"repeat":false}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos/publish/preview":{"post":{"operationId":"shared_videos_publish_preview","summary":"See exactly what publish would post (the video, each account, each caption) without posting anything.","description":"Takes the same fields as POST /videos/publish and answers with the preview an AI app would show: the video, each account and the exact caption it gets. Accounts that already have this video are marked, and problems says what publish would refuse. For a Studio 2.0 film, notes says how many moments the free Review check still flags (the app shows this before it posts; it never stops the post). Posts nothing. Free.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.videos.publish_preview","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product":{"description":"Which kind of video: v3 (a V3 cinematic story), studio (a Studio 2.0 film), ce (a Character Explainer video), stickman (a Stickman video or Story part) or fruit (a Fruit AI or Animal story, or a series part).","type":"string","enum":["v3","studio","ce","stickman","fruit"]},"projectId":{"description":"The project id: a V3 project id, a Studio 2.0 project id, a Character Explainer video (session) id, a Stickman video id, or a Fruit story id.","type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"videoId":{"description":"Studio 2.0 only: which finished cut to post (an id from studio_projects get with include videos). Leave it out to post the cut selected in the app.","type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-][A-Za-z0-9_.:-]*$"},"accountIds":{"description":"The accounts to post to, one per platform at most (ids from the accounts action).","minItems":1,"maxItems":6,"type":"array","items":{"description":"A connected account id from the accounts action.","type":"string","pattern":"^[a-f0-9]{24}$"}},"title":{"description":"Use this title instead of the video's own (YouTube shows it as the title; other platforms put it above the caption).","type":"string","minLength":1,"maxLength":100},"description":{"description":"Use this caption text instead of the video's own. X and Snapchat get it shortened to fit.","type":"string","minLength":1,"maxLength":2000},"hashtags":{"description":"Use these hashtags instead of the video's own. At most 5 are posted. An empty list posts none.","maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":60,"pattern":"^#?[^\\s#,]+$"}},"youtubePrivacy":{"description":"YouTube visibility. Default: public.","type":"string","enum":["public","unlisted","private"]},"youtubeCategoryId":{"description":"YouTube category: 2 Autos & Vehicles, 23 Comedy, 27 Education, 24 Entertainment, 1 Film & Animation, 20 Gaming, 26 Howto & Style, 10 Music, 25 News & Politics, 29 Nonprofits & Activism, 22 People & Blogs, 15 Pets & Animals, 28 Science & Technology, 17 Sports, 19 Travel & Events. Default: 22 (People & Blogs).","type":"string","enum":["1","2","10","15","17","19","20","22","23","24","25","26","27","28","29"]},"aiDisclosure":{"description":"Label the post as AI-made where the platform supports it (YouTube, TikTok). Default: true.","type":"boolean"},"coverMediaId":{"description":"A picture from your media library (autoclips_media) to post as the thumbnail of this post only, in place of the video's own cover (autoclips_covers). YouTube, TikTok, Instagram and Facebook show it; X and Snapchat show their own frame. Kept as it is, saved as a JPEG of at most 2 MB.","type":"string","pattern":"^[a-fA-F0-9]{24}$"},"again":{"description":"true to post to an account that already has this video, or may have it (posted in the last 30 days through the API, posted by the app itself when the video finished or by the automation that made it, in the Studio film's publish history, or a post that got no clear answer). Leave it out otherwise.","type":"boolean"}},"required":["product","projectId","accountIds"],"additionalProperties":false},"example":{"product":"v3","projectId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","accountIds":["66f1a2b3c4d5e6f708192a3b"]}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"video":{"type":"object","properties":{"product":{"type":"string","enum":["v3","studio","ce","stickman","fruit"]},"projectId":{"type":"string"},"videoId":{"description":"Studio 2.0: the cut that is posted.","anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"url":{"description":"The video that is posted.","type":"string"}},"required":["product","projectId","videoId","title","url"],"additionalProperties":false},"posts":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string","enum":["youtube","tiktok","instagram","facebook","twitter","snapchat"]},"platformName":{"type":"string"},"account":{"description":"The account name, as the app shows it.","type":"string"},"youtubeTitle":{"type":"string"},"youtubePrivacy":{"type":"string","enum":["public","unlisted","private"]},"youtubeCategory":{"type":"string"},"caption":{"description":"The exact text this account gets.","type":"string"},"aiLabel":{"type":"boolean"},"alreadyPosted":{"description":"Set when this account already has this video.","type":"string"},"note":{"type":"string"}},"required":["accountId","platform","platformName","account","caption","aiLabel"],"additionalProperties":false}},"cover":{"description":"The thumbnail the posts carry.","type":"object","properties":{"from":{"description":"yours: the picture you sent as coverMediaId; video: the video's own cover (autoclips_covers); none: each platform picks a frame.","type":"string","enum":["yours","video","none"]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"platforms":{"description":"The platforms that show it. X and Snapchat take no cover.","type":"array","items":{"type":"string"}}},"required":["from","url","platforms"],"additionalProperties":false},"again":{"type":"boolean"},"notes":{"description":"What the app's own confirm says before it posts, besides the posts: for a Studio 2.0 film, how many moments the free Review check still flags. Show it with the preview; it never stops the post.","type":"array","items":{"type":"string"}},"ready":{"description":"Whether publish would post with these fields right now.","type":"boolean"},"problems":{"type":"array","items":{"type":"string"}}},"required":["video","posts","again","ready","problems"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"video":{"product":"v3","projectId":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","videoId":null,"title":"The lighthouse keeper","url":"https://media.autoclips.app/videos/v3/lighthouse.mp4"},"posts":[{"accountId":"66f1a2b3c4d5e6f708192a3b","platform":"tiktok","platformName":"TikTok","account":"@lighthousetales","caption":"The lighthouse keeper\n\nEvery night he climbed the stairs.\n\n#mystery #lighthouse","aiLabel":true}],"again":false,"ready":true,"problems":[]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/voices":{"get":{"operationId":"shared_voices_list","summary":"List the voices you can use: the AutoClips library and your own cloned voices.","description":"Your own cloned voices come first, then the AutoClips library. Search by name, accent, description or language. `uses` says whether a voice can narrate a V3 video, be a V3 character's voice, or both. Other customers' cloned voices are never listed.\n\n**Permissions:** read.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["read"]}],"x-autoclips-operation":"shared.voices.list","x-autoclips-scopes":["read"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_voices action=list","parameters":[{"name":"search","in":"query","required":false,"schema":{"description":"Only voices whose name, accent or description contains this text, for example \"british\" or \"Josh\". A language's name or code (\"spanish\", \"Español\", \"es\") also finds the voices the library lists for that language.","type":"string","minLength":1,"maxLength":60},"description":"Only voices whose name, accent or description contains this text, for example \"british\" or \"Josh\". A language's name or code (\"spanish\", \"Español\", \"es\") also finds the voices the library lists for that language.","example":"british"},{"name":"source","in":"query","required":false,"schema":{"description":"library = AutoClips voices, cloned = your own, all (default).","type":"string","enum":["all","library","cloned"]},"description":"library = AutoClips voices, cloned = your own, all (default).","example":"library"},{"name":"limit","in":"query","required":false,"schema":{"description":"How many voices to return (1-100, default 50).","type":"integer","minimum":1,"maximum":100},"description":"How many voices to return (1-100, default 50).","example":10}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"voices":{"type":"array","items":{"type":"object","properties":{"voiceId":{"description":"Use this id (or the name) wherever a voice is asked for.","type":"string"},"name":{"type":"string"},"source":{"description":"library = an AutoClips voice; cloned = one of your own cloned voices.","type":"string","enum":["library","cloned"]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"accent":{"anyOf":[{"type":"string"},{"type":"null"}]},"languages":{"description":"The languages the voice library lists for this voice, as codes (\"es\" for Spanish); empty when it lists none. Search by a language's name to find them.","type":"array","items":{"type":"string"}},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"previewUrl":{"description":"A short sample to listen to, when there is one.","anyOf":[{"type":"string"},{"type":"null"}]},"recommended":{"description":"One of the voices AutoClips picked for narration.","type":"boolean"},"uses":{"description":"narrator = can narrate a V3 video; character = can be a V3 character's voice.","type":"array","items":{"type":"string","enum":["narrator","character"]}},"createdAt":{"description":"When you cloned it (your own voices only).","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["voiceId","name","source","gender","accent","description","previewUrl","recommended","uses","createdAt"],"additionalProperties":false}},"total":{"description":"How many voices matched before the limit.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"truncated":{"description":"True when more voices matched than were returned. Search to narrow them down.","type":"boolean"},"note":{"description":"Set when the full library could not be reached and only the recommended voices are shown, and when the search named a language (how voices were matched to it).","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["voices","total","truncated","note"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"voices":[{"voiceId":"a1b2c3d4e5f6a7b8c9d0","name":"My podcast voice","source":"cloned","gender":null,"accent":null,"languages":[],"description":"Your cloned voice.","previewUrl":null,"recommended":false,"uses":["narrator","character"],"createdAt":"2026-09-20T09:30:00.000Z"},{"voiceId":"TxGEqnHWrfWFTfGW9XjX","name":"Josh","source":"library","gender":"male","accent":"american","languages":["en"],"description":"Classic YouTube narrator - clear & engaging","previewUrl":null,"recommended":true,"uses":["narrator","character"],"createdAt":null}],"total":2,"truncated":false,"note":null}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/voices/clone":{"post":{"operationId":"shared_voices_clone","summary":"Clone your own voice from a recording in your media library, to narrate your videos.","description":"Makes a narrator voice from a sound recording already in your media library: 20 seconds to 5 minutes of one person speaking clearly (1 to 2 minutes sounds best), with no music or background noise. Bring the recording in first with autoclips_media (upload_link or import_url), then send its media id, a name, and consent: true to confirm it is your own voice or you have permission to use it. The voice uses the recording from trimStartSeconds (default the start), cut to 5 minutes; at least 20 seconds must be left after that point. The new voice narrates: use its voiceId (or name) as the voice of a Stickman Story or a V3 video, or as a V3 character's voice. It lists in autoclips_voices list, and the website shows it too. Free, but your plan sets how many cloned voices you can keep, and free plans cannot clone. Delete one with autoclips_voices delete to make room. Cloning takes up to two minutes. If a call seems lost, calling again with the same recording and name within 10 minutes answers the voice already made (alreadyMade: true) instead of making a second one. Over REST, an Idempotency-Key does the same. For a short voice that only V3 characters speak with, use the clone action instead.\n\n**Permissions:** edit.\n**Cost:** Free.","tags":["Account, media and publishing"],"security":[{"bearerAuth":["edit"]}],"x-autoclips-operation":"shared.voices.clone","x-autoclips-scopes":["edit"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_voices action=clone_narrator","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mediaId":{"description":"A sound recording in your media library (autoclips_media list, upload_link or import_url): 20 seconds to 5 minutes of one person speaking clearly (1 to 2 minutes sounds best), up to 50 MB. A longer recording is cut to 5 minutes.","type":"string","pattern":"^[a-fA-F0-9]{24}$"},"name":{"description":"What to call the voice (1 to 50 characters), for example \"My voice\". You can pick it by this name later.","type":"string","minLength":1,"maxLength":50,"pattern":"^[^\\u0000-\\u001f\\u007f‪-‮⁦-⁩]+$"},"trimStartSeconds":{"description":"Where in the recording the voice starts, in seconds (default 0). From there up to 5 minutes are used.","type":"number","minimum":0,"maximum":36000},"consent":{"description":"Must be true: you confirm this is your own voice, or that you have permission to use it.","type":"boolean","const":true}},"required":["mediaId","name","consent"],"additionalProperties":false},"example":{"mediaId":"66f7c0ffee00000000000004","name":"My voice","consent":true}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"voice":{"description":"The voice. Use its voiceId (or name) wherever a narrator voice is asked for.","type":"object","properties":{"voiceId":{"description":"Use this id (or the name) wherever a voice is asked for.","type":"string"},"name":{"type":"string"},"source":{"description":"library = an AutoClips voice; cloned = one of your own cloned voices.","type":"string","enum":["library","cloned"]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"accent":{"anyOf":[{"type":"string"},{"type":"null"}]},"languages":{"description":"The languages the voice library lists for this voice, as codes (\"es\" for Spanish); empty when it lists none. Search by a language's name to find them.","type":"array","items":{"type":"string"}},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"previewUrl":{"description":"A short sample to listen to, when there is one.","anyOf":[{"type":"string"},{"type":"null"}]},"recommended":{"description":"One of the voices AutoClips picked for narration.","type":"boolean"},"uses":{"description":"narrator = can narrate a V3 video; character = can be a V3 character's voice.","type":"array","items":{"type":"string","enum":["narrator","character"]}},"createdAt":{"description":"When you cloned it (your own voices only).","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["voiceId","name","source","gender","accent","description","previewUrl","recommended","uses","createdAt"],"additionalProperties":false},"alreadyMade":{"description":"True when this recording was already cloned under this name in the last 10 minutes: that voice is returned and nothing new was made.","type":"boolean"},"secondsUsed":{"description":"How many seconds of the recording made the voice (null when alreadyMade).","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["voice","alreadyMade","secondsUsed"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"voice":{"voiceId":"a1b2c3d4e5f6a7b8c9d0","name":"My voice","source":"cloned","gender":null,"accent":null,"languages":[],"description":"Your cloned voice.","previewUrl":null,"recommended":false,"uses":["narrator","character"],"createdAt":"2026-10-27T10:15:00.000Z"},"alreadyMade":false,"secondsUsed":184.2}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/voices/{voiceId}":{"delete":{"operationId":"shared_voices_delete","summary":"Remove one of your own cloned voices from your AutoClips voices.","description":"Only your own cloned voices can be removed; AutoClips library voices cannot. Every saved copy of the voice on your account goes (the answer says how many). Videos already made keep their sound. Characters that use the voice keep pointing at it until you give them another voice (v3_characters update); the answer lists them.\n\n**Permissions:** delete.\n**Cost:** Free.\n**Deletes data.**","tags":["Account, media and publishing"],"security":[{"bearerAuth":["delete"]}],"x-autoclips-operation":"shared.voices.delete","x-autoclips-scopes":["delete"],"x-autoclips-cost":"free","x-autoclips-mcp":"autoclips_voices action=delete","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"voiceId","in":"path","required":true,"schema":{"description":"The id of one of your own cloned voices, from list.","type":"string","pattern":"^[A-Za-z0-9_-]{6,64}$"},"description":"The id of one of your own cloned voices, from list.","example":"a1b2c3d4e5f6a7b8c9d0"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"A fresh random value (a UUID) per new request. Retrying with the same key never runs or charges twice."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"voiceId":{"type":"string"},"deleted":{"type":"boolean"},"copiesRemoved":{"description":"How many saved copies of this voice were removed from your account (the app could save the same voice more than once).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charactersUsingIt":{"description":"Your characters that still point at this voice. Give them another voice.","type":"array","items":{"type":"string"}}},"required":["voiceId","deleted","copiesRemoved","charactersUsingIt"],"additionalProperties":false},"meta":{"type":"object","additionalProperties":true,"properties":{"idempotentReplay":{"type":"boolean","description":"true when this is the stored answer to the same request sent before with the same Idempotency-Key (the Idempotent-Replayed header says the same): nothing ran or was charged again."}}}},"required":["data"]},"example":{"data":{"voiceId":"a1b2c3d4e5f6a7b8c9d0","deleted":true,"copiesRemoved":1,"charactersUsingIt":[]}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"headers":{"X-Request-Id":{"description":"The id of this request. Mention it if you contact us about a request.","schema":{"type":"string"},"example":"req_4f0c1d2e3b4a59687766554e"},"RateLimit":{"description":"What is left, in the IETF draft format (draft-ietf-httpapi-ratelimit-headers, -08 and later). `\"minute\"` is the per-account limit per minute; each daily limit this request counted against follows under its own name (`create`, `ai_free`, `upload`, `upload_link`, `publish`, `finish`, `promotion_extract`, the same name as `details.limit` on a 429). `r` = how many are left, `t` = seconds until it starts again.","schema":{"type":"string"},"example":"\"minute\";r=117;t=42, \"ai_free\";r=37;t=37211"},"RateLimit-Policy":{"description":"The limits behind `RateLimit`: `q` = how many are allowed, `w` = the window in seconds (60 for the minute, 86400 for a daily limit, whose day starts at 00:00 UTC).","schema":{"type":"string"},"example":"\"minute\";q=120;w=60, \"ai_free\";q=40;w=86400"},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this account: the `\"minute\"` item of `RateLimit-Policy`.","schema":{"type":"integer"},"example":120},"X-RateLimit-Remaining":{"description":"Requests left in this minute.","schema":{"type":"integer"},"example":117},"X-RateLimit-Reset":{"description":"Seconds (not a time) until the count for this minute starts again.","schema":{"type":"integer"},"example":42},"Retry-After":{"description":"On every 429: how many seconds to wait. For a daily limit, the seconds until 00:00 UTC; `details.resetsAt` says the moment.","schema":{"type":"integer"},"example":18},"Idempotent-Replayed":{"description":"`true` when this is the stored answer to the same request sent before with the same Idempotency-Key.","schema":{"type":"string","enum":["true"]}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (ac_live_…) or an OAuth access token. Scopes: read (See your projects and videos); edit (Change your projects); spend (Spend credits); delete (Delete things); publish (Post to your social accounts)."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","idempotency_key_required","unauthorized","confirmation_required","quote_exceeds_max_credits","insufficient_credits","daily_credit_cap_reached","insufficient_scope","plan_required","forbidden","staging_not_allowlisted","not_found","method_not_allowed","conflict","revision_conflict","idempotency_key_reused","idempotency_in_progress","confirmation_invalid","gone","payload_too_large","unsupported_media_type","rate_limited","daily_limit_reached","internal_error","not_implemented","unavailable"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true},"docs_url":{"type":"string"}}}}}}}}