{"openapi":"3.1.0","info":{"title":"AutoClips API","version":"1.0.0","description":"Create, edit and check Character Explainer, 3D Animated Studio 2.0 and AutoClips V3 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.\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.*` and `shared.videos.*`), 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"}],"paths":{"/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","fr","de","pt","it","ru","hi","ja","ko","zh","th","ta","vi","id","fil","ms","pl","tr","nl","sv","cs","da","fi","el","hu","no","ro","sk","uk","bg","hr","lt","ka","ar"]},"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","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","fr","de","pt","it","ru","hi","ja","ko","zh","th","ta","vi","id","fil","ms","pl","tr","nl","sv","cs","da","fi","el","hu","no","ro","sk","uk","bg","hr","lt","ka","ar"],"defaultPersonality":"authority"}],"count":2}}}}},"400":{"description":"`invalid_request`, `idempotency_key_required`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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":{"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).\nChoices:\n- en — English: English script, voices and captions.\n- es — Spanish: Spanish script, voices and captions.\n- fr — French: French script, voices and captions.\n- de — German: German script, voices and captions.\n- pt — Portuguese: Portuguese script, voices and captions.\n- it — Italian: Italian script, voices and captions.\n- ru — Russian: Russian script, voices and captions.\n- hi — Hindi: Hindi script, voices and captions.\n- ja — Japanese: Japanese script, voices and captions.\n- ko — Korean: Korean script, voices and captions.\n- zh — Chinese: Chinese script, voices and captions.\n- th — Thai: Thai script, voices and captions.\n- ta — Tamil: Tamil script, voices and captions.\n- vi — Vietnamese: Vietnamese script, voices and captions.\n- id — Indonesian: Indonesian script, voices and captions.\n- fil — Filipino: Filipino script, voices and captions.\n- ms — Malay: Malay script, voices and captions.\n- pl — Polish: Polish script, voices and captions.\n- tr — Turkish: Turkish script, voices and captions.\n- nl — Dutch: Dutch script, voices and captions.\n- sv — Swedish: Swedish script, voices and captions.\n- cs — Czech: Czech script, voices and captions.\n- da — Danish: Danish script, voices and captions.\n- fi — Finnish: Finnish script, voices and captions.\n- el — Greek: Greek script, voices and captions.\n- hu — Hungarian: Hungarian script, voices and captions.\n- no — Norwegian: Norwegian script, voices and captions.\n- ro — Romanian: Romanian script, voices and captions.\n- sk — Slovak: Slovak script, voices and captions.\n- uk — Ukrainian: Ukrainian script, voices and captions.\n…and 5 more: call autoclips_options (GET /api/v1/options?product=ce&option=language) to see them all.\nDefault: en.","type":"string","enum":["en","es","fr","de","pt","it","ru","hi","ja","ko","zh","th","ta","vi","id","fil","ms","pl","tr","nl","sv","cs","da","fi","el","hu","no","ro","sk","uk","bg","hr","lt","ka","ar"]},"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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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":{"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).\nChoices:\n- en — English: English script, voices and captions.\n- es — Spanish: Spanish script, voices and captions.\n- fr — French: French script, voices and captions.\n- de — German: German script, voices and captions.\n- pt — Portuguese: Portuguese script, voices and captions.\n- it — Italian: Italian script, voices and captions.\n- ru — Russian: Russian script, voices and captions.\n- hi — Hindi: Hindi script, voices and captions.\n- ja — Japanese: Japanese script, voices and captions.\n- ko — Korean: Korean script, voices and captions.\n- zh — Chinese: Chinese script, voices and captions.\n- th — Thai: Thai script, voices and captions.\n- ta — Tamil: Tamil script, voices and captions.\n- vi — Vietnamese: Vietnamese script, voices and captions.\n- id — Indonesian: Indonesian script, voices and captions.\n- fil — Filipino: Filipino script, voices and captions.\n- ms — Malay: Malay script, voices and captions.\n- pl — Polish: Polish script, voices and captions.\n- tr — Turkish: Turkish script, voices and captions.\n- nl — Dutch: Dutch script, voices and captions.\n- sv — Swedish: Swedish script, voices and captions.\n- cs — Czech: Czech script, voices and captions.\n- da — Danish: Danish script, voices and captions.\n- fi — Finnish: Finnish script, voices and captions.\n- el — Greek: Greek script, voices and captions.\n- hu — Hungarian: Hungarian script, voices and captions.\n- no — Norwegian: Norwegian script, voices and captions.\n- ro — Romanian: Romanian script, voices and captions.\n- sk — Slovak: Slovak script, voices and captions.\n- uk — Ukrainian: Ukrainian script, voices and captions.\n…and 5 more: call autoclips_options (GET /api/v1/options?product=ce&option=language) to see them all.\nDefault: en.","type":"string","enum":["en","es","fr","de","pt","it","ru","hi","ja","ko","zh","th","ta","vi","id","fil","ms","pl","tr","nl","sv","cs","da","fi","el","hu","no","ro","sk","uk","bg","hr","lt","ka","ar"]},"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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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":{"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).\nChoices:\n- en — English: English script, voices and captions.\n- es — Spanish: Spanish script, voices and captions.\n- fr — French: French script, voices and captions.\n- de — German: German script, voices and captions.\n- pt — Portuguese: Portuguese script, voices and captions.\n- it — Italian: Italian script, voices and captions.\n- ru — Russian: Russian script, voices and captions.\n- hi — Hindi: Hindi script, voices and captions.\n- ja — Japanese: Japanese script, voices and captions.\n- ko — Korean: Korean script, voices and captions.\n- zh — Chinese: Chinese script, voices and captions.\n- th — Thai: Thai script, voices and captions.\n- ta — Tamil: Tamil script, voices and captions.\n- vi — Vietnamese: Vietnamese script, voices and captions.\n- id — Indonesian: Indonesian script, voices and captions.\n- fil — Filipino: Filipino script, voices and captions.\n- ms — Malay: Malay script, voices and captions.\n- pl — Polish: Polish script, voices and captions.\n- tr — Turkish: Turkish script, voices and captions.\n- nl — Dutch: Dutch script, voices and captions.\n- sv — Swedish: Swedish script, voices and captions.\n- cs — Czech: Czech script, voices and captions.\n- da — Danish: Danish script, voices and captions.\n- fi — Finnish: Finnish script, voices and captions.\n- el — Greek: Greek script, voices and captions.\n- hu — Hungarian: Hungarian script, voices and captions.\n- no — Norwegian: Norwegian script, voices and captions.\n- ro — Romanian: Romanian script, voices and captions.\n- sk — Slovak: Slovak script, voices and captions.\n- uk — Ukrainian: Ukrainian script, voices and captions.\n…and 5 more: call autoclips_options (GET /api/v1/options?product=ce&option=language) to see them all.\nDefault: the project's saved choice (leave it out).","type":"string","enum":["en","es","fr","de","pt","it","ru","hi","ja","ko","zh","th","ta","vi","id","fil","ms","pl","tr","nl","sv","cs","da","fi","el","hu","no","ro","sk","uk","bg","hr","lt","ka","ar"]},"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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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. It is free, 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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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 or studio.","type":"string","enum":["shared","v3","ce","studio"]},"description":"Only jobs from this product: shared, v3, ce or studio.","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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, all (default).","type":"string","enum":["upload","ai","all"]},"description":"upload = files people uploaded, ai = files AutoClips generated, 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","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.","type":"string","enum":["upload","ai"]}},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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.","type":"string","enum":["upload","ai"]}},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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.","type":"string","enum":["upload","ai"]}},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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.","type":"string","enum":["upload","ai"]}},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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.","type":"string","enum":["upload","ai"]}},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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.\nDefault: Every product (leave it out).","type":"string","enum":["shared","v3","ce","studio"]},"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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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":2736,"breakdown":[{"label":"Script (standard writer)","credits":25},{"label":"Narration","credits":186},{"label":"Moving clips made straight from the script (AutoClips, every scene)","credits":2242},{"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 883 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. 2736 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 (900 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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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,"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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"]},"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","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,"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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"]}},"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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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"},"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","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"]},"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"},"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","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,"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,"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"},"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","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,"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,"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"},"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","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,"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,"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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"},"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","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"},"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","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,"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"},"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","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,"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,"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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,"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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"},"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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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. 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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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) or studio (a Studio 2.0 video).","type":"string","enum":["v3","studio"]},"description":"Which product the video belongs to: v3 (a V3 cinematic story) or studio (a Studio 2.0 video).","example":"v3"},{"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":"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","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"product":{"type":"string","enum":["v3","studio"]},"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},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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. 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. 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; 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. Default 4 seconds for a picture, 5 for a video.","type":"integer","minimum":250,"maximum":30000}},"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 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":"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 or the speed of the whole video.","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}},"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) or studio (a Studio 2.0 video).","type":"string","enum":["v3","studio"]},"description":"Which product the video belongs to: v3 (a V3 cinematic story) or studio (a Studio 2.0 video).","example":"v3"},{"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":"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","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"]},"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},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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) or studio (a Studio 2.0 video).","type":"string","enum":["v3","studio"]},"description":"Which product the video belongs to: v3 (a V3 cinematic story) or studio (a Studio 2.0 video).","example":"v3"},{"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":"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","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"]},"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},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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) or studio (a Studio 2.0 video).","type":"string","enum":["v3","studio"]},"description":"Which product the video belongs to: v3 (a V3 cinematic story) or studio (a Studio 2.0 video).","example":"studio"},{"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":"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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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) or studio (a Studio 2.0 video).","type":"string","enum":["v3","studio"]},"description":"Which product the video belongs to: v3 (a V3 cinematic story) or studio (a Studio 2.0 video).","example":"v3"},{"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":"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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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) or studio (a Studio 2.0 video).","type":"string","enum":["v3","studio"]},"description":"Which product the video belongs to: v3 (a V3 cinematic story) or studio (a Studio 2.0 video).","example":"studio"},{"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":"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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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) or studio (a Studio 2.0 video).","type":"string","enum":["v3","studio"]},"description":"Which product the video belongs to: v3 (a V3 cinematic story) or studio (a Studio 2.0 video).","example":"studio"},{"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":"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","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"]},"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},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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) or studio (a Studio 2.0 video).","type":"string","enum":["v3","studio"]},"description":"Which product the video belongs to: v3 (a V3 cinematic story) or studio (a Studio 2.0 video).","example":"v3"},{"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":"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","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"]},"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},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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. 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- autoclipsVideo — Best value (AutoClips): Our own video model: natural motion, 5-second clips, every shape. The only one that can make clips straight from the script (see directVideo). (59 credits per clip until 31 October 2026, then 119)\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)\nDefault: autoclipsVideo.","type":"string","enum":["autoclipsVideo","seedancePro","seedanceLite","kling3Video","klingVideo","grokImagineVideo","omniMax"]},"directVideo":{"description":"Clips straight from the script: Only when Movement is every_scene on AutoClips (animationModel autoclipsVideo): each clip is made straight from the script, with no picture drawn for it first; with consistent characters on, from the character and place pictures too. Without consistent characters it costs less: no picture is paid for, each clip costs the AutoClips clip price, and people and places can change between clips. With consistent characters, no picture per clip is paid for, but a clip made from your character and place pictures costs more than a plain one (119 credits a clip until 31 October 2026, then 237), plus up to 9 character and place pictures at 25 credits each. 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":{"description":"Language: The language of the narration, captions and title.\nChoices:\n- en — English: English narration and captions.\n- es — Spanish: Spanish narration and captions.\n- fr — French: French narration and captions.\n- de — German: German narration and captions.\n- pt — Portuguese: Portuguese narration and captions.\n- it — Italian: Italian narration and captions.\n- ru — Russian: Russian narration and captions.\n- hi — Hindi: Hindi narration and captions.\n- ja — Japanese: Japanese narration and captions.\n- ko — Korean: Korean narration and captions.\n- zh — Chinese: Chinese narration and captions.\n- th — Thai: Thai narration and captions.\n- ta — Tamil: Tamil narration and captions.\n- vi — Vietnamese: Vietnamese narration and captions.\n- id — Indonesian: Indonesian narration and captions.\n- fil — Filipino: Filipino narration and captions.\n- ms — Malay: Malay narration and captions.\n- pl — Polish: Polish narration and captions.\n- tr — Turkish: Turkish narration and captions.\n- nl — Dutch: Dutch narration and captions.\n- sv — Swedish: Swedish narration and captions.\n- cs — Czech: Czech narration and captions.\n- da — Danish: Danish narration and captions.\n- fi — Finnish: Finnish narration and captions.\n- el — Greek: Greek narration and captions.\n- hu — Hungarian: Hungarian narration and captions.\n- no — Norwegian: Norwegian narration and captions.\n- ro — Romanian: Romanian narration and captions.\n- sk — Slovak: Slovak narration and captions.\n- uk — Ukrainian: Ukrainian narration and captions.\n…and 5 more: call autoclips_options (GET /api/v1/options?product=v3&option=language) to see them all.\nDefault: en.","type":"string","enum":["en","es","fr","de","pt","it","ru","hi","ja","ko","zh","th","ta","vi","id","fil","ms","pl","tr","nl","sv","cs","da","fi","el","hu","no","ro","sk","uk","bg","hr","lt","ka","ar"]},"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.","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 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"},"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"},"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_.:-]*$"}},"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","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":"autoclipsVideo","directVideo":true,"consistency":false,"language":"en","voiceId":null,"voiceModel":"eleven_v4","captions":true,"subjectWobble":false,"hookIntro":null,"cliffhanger":false},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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). 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- autoclipsVideo — Best value (AutoClips): Our own video model: natural motion, 5-second clips, every shape. The only one that can make clips straight from the script (see directVideo). (59 credits per clip until 31 October 2026, then 119)\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)\nDefault: autoclipsVideo.","type":"string","enum":["autoclipsVideo","seedancePro","seedanceLite","kling3Video","klingVideo","grokImagineVideo","omniMax"]},"directVideo":{"description":"Clips straight from the script: Only when Movement is every_scene on AutoClips (animationModel autoclipsVideo): each clip is made straight from the script, with no picture drawn for it first; with consistent characters on, from the character and place pictures too. Without consistent characters it costs less: no picture is paid for, each clip costs the AutoClips clip price, and people and places can change between clips. With consistent characters, no picture per clip is paid for, but a clip made from your character and place pictures costs more than a plain one (119 credits a clip until 31 October 2026, then 237), plus up to 9 character and place pictures at 25 credits each. 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":{"description":"Language: The language of the narration, captions and title.\nChoices:\n- en — English: English narration and captions.\n- es — Spanish: Spanish narration and captions.\n- fr — French: French narration and captions.\n- de — German: German narration and captions.\n- pt — Portuguese: Portuguese narration and captions.\n- it — Italian: Italian narration and captions.\n- ru — Russian: Russian narration and captions.\n- hi — Hindi: Hindi narration and captions.\n- ja — Japanese: Japanese narration and captions.\n- ko — Korean: Korean narration and captions.\n- zh — Chinese: Chinese narration and captions.\n- th — Thai: Thai narration and captions.\n- ta — Tamil: Tamil narration and captions.\n- vi — Vietnamese: Vietnamese narration and captions.\n- id — Indonesian: Indonesian narration and captions.\n- fil — Filipino: Filipino narration and captions.\n- ms — Malay: Malay narration and captions.\n- pl — Polish: Polish narration and captions.\n- tr — Turkish: Turkish narration and captions.\n- nl — Dutch: Dutch narration and captions.\n- sv — Swedish: Swedish narration and captions.\n- cs — Czech: Czech narration and captions.\n- da — Danish: Danish narration and captions.\n- fi — Finnish: Finnish narration and captions.\n- el — Greek: Greek narration and captions.\n- hu — Hungarian: Hungarian narration and captions.\n- no — Norwegian: Norwegian narration and captions.\n- ro — Romanian: Romanian narration and captions.\n- sk — Slovak: Slovak narration and captions.\n- uk — Ukrainian: Ukrainian narration and captions.\n…and 5 more: call autoclips_options (GET /api/v1/options?product=v3&option=language) to see them all.\nDefault: en.","type":"string","enum":["en","es","fr","de","pt","it","ru","hi","ja","ko","zh","th","ta","vi","id","fil","ms","pl","tr","nl","sv","cs","da","fi","el","hu","no","ro","sk","uk","bg","hr","lt","ka","ar"]},"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.","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 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"},"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"},"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_.:-]*$"}},"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 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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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- 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.\nWhile Quick Create is running only captions and publishing 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- autoclipsVideo — Best value (AutoClips): Our own video model: natural motion, 5-second clips, every shape. The only one that can make clips straight from the script (see directVideo). (59 credits per clip until 31 October 2026, then 119)\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)\nDefault: autoclipsVideo.","type":"string","enum":["autoclipsVideo","seedancePro","seedanceLite","kling3Video","klingVideo","grokImagineVideo","omniMax"]},"directVideo":{"description":"Clips straight from the script: Only when Movement is every_scene on AutoClips (animationModel autoclipsVideo): each clip is made straight from the script, with no picture drawn for it first; with consistent characters on, from the character and place pictures too. Without consistent characters it costs less: no picture is paid for, each clip costs the AutoClips clip price, and people and places can change between clips. With consistent characters, no picture per clip is paid for, but a clip made from your character and place pictures costs more than a plain one (119 credits a clip until 31 October 2026, then 237), plus up to 9 character and place pictures at 25 credits each. 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":{"description":"Language: The language of the narration, captions and title.\nChoices:\n- en — English: English narration and captions.\n- es — Spanish: Spanish narration and captions.\n- fr — French: French narration and captions.\n- de — German: German narration and captions.\n- pt — Portuguese: Portuguese narration and captions.\n- it — Italian: Italian narration and captions.\n- ru — Russian: Russian narration and captions.\n- hi — Hindi: Hindi narration and captions.\n- ja — Japanese: Japanese narration and captions.\n- ko — Korean: Korean narration and captions.\n- zh — Chinese: Chinese narration and captions.\n- th — Thai: Thai narration and captions.\n- ta — Tamil: Tamil narration and captions.\n- vi — Vietnamese: Vietnamese narration and captions.\n- id — Indonesian: Indonesian narration and captions.\n- fil — Filipino: Filipino narration and captions.\n- ms — Malay: Malay narration and captions.\n- pl — Polish: Polish narration and captions.\n- tr — Turkish: Turkish narration and captions.\n- nl — Dutch: Dutch narration and captions.\n- sv — Swedish: Swedish narration and captions.\n- cs — Czech: Czech narration and captions.\n- da — Danish: Danish narration and captions.\n- fi — Finnish: Finnish narration and captions.\n- el — Greek: Greek narration and captions.\n- hu — Hungarian: Hungarian narration and captions.\n- no — Norwegian: Norwegian narration and captions.\n- ro — Romanian: Romanian narration and captions.\n- sk — Slovak: Slovak narration and captions.\n- uk — Ukrainian: Ukrainian narration and captions.\n…and 5 more: call autoclips_options (GET /api/v1/options?product=v3&option=language) to see them all.\nDefault: en.","type":"string","enum":["en","es","fr","de","pt","it","ru","hi","ja","ko","zh","th","ta","vi","id","fil","ms","pl","tr","nl","sv","cs","da","fi","el","hu","no","ro","sk","uk","bg","hr","lt","ka","ar"]},"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.","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 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"},"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"},"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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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.","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":{"description":"Language: The language of the narration, captions and title.\nChoices:\n- en — English: English narration and captions.\n- es — Spanish: Spanish narration and captions.\n- fr — French: French narration and captions.\n- de — German: German narration and captions.\n- pt — Portuguese: Portuguese narration and captions.\n- it — Italian: Italian narration and captions.\n- ru — Russian: Russian narration and captions.\n- hi — Hindi: Hindi narration and captions.\n- ja — Japanese: Japanese narration and captions.\n- ko — Korean: Korean narration and captions.\n- zh — Chinese: Chinese narration and captions.\n- th — Thai: Thai narration and captions.\n- ta — Tamil: Tamil narration and captions.\n- vi — Vietnamese: Vietnamese narration and captions.\n- id — Indonesian: Indonesian narration and captions.\n- fil — Filipino: Filipino narration and captions.\n- ms — Malay: Malay narration and captions.\n- pl — Polish: Polish narration and captions.\n- tr — Turkish: Turkish narration and captions.\n- nl — Dutch: Dutch narration and captions.\n- sv — Swedish: Swedish narration and captions.\n- cs — Czech: Czech narration and captions.\n- da — Danish: Danish narration and captions.\n- fi — Finnish: Finnish narration and captions.\n- el — Greek: Greek narration and captions.\n- hu — Hungarian: Hungarian narration and captions.\n- no — Norwegian: Norwegian narration and captions.\n- ro — Romanian: Romanian narration and captions.\n- sk — Slovak: Slovak narration and captions.\n- uk — Ukrainian: Ukrainian narration and captions.\n…and 5 more: call autoclips_options (GET /api/v1/options?product=v3&option=language) to see them all.\nDefault: en.","type":"string","enum":["en","es","fr","de","pt","it","ru","hi","ja","ko","zh","th","ta","vi","id","fil","ms","pl","tr","nl","sv","cs","da","fi","el","hu","no","ro","sk","uk","bg","hr","lt","ka","ar"]},"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","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"]},"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":"autoclipsVideo","directVideo":false,"consistency":false,"language":"en","voiceId":null,"voiceModel":"eleven_v4","captions":true,"subjectWobble":false,"hookIntro":null,"cliffhanger":false},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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":"autoclipsVideo","directVideo":false,"consistency":false,"language":"en","voiceId":null,"voiceModel":"eleven_v4","captions":true,"subjectWobble":false,"hookIntro":null,"cliffhanger":false},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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":"autoclipsVideo","directVideo":false,"consistency":false,"language":"en","voiceId":null,"voiceModel":"eleven_v4","captions":true,"subjectWobble":false,"hookIntro":null,"cliffhanger":false},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`confirmation_required`, `quote_exceeds_max_credits`, `insufficient_credits`, `daily_credit_cap_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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":"autoclipsVideo","directVideo":false,"consistency":false,"language":"en","voiceId":null,"voiceModel":"eleven_v4","captions":true,"subjectWobble":false,"hookIntro":null,"cliffhanger":false},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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":"autoclipsVideo","directVideo":false,"consistency":false,"language":"en","voiceId":null,"voiceModel":"eleven_v4","captions":true,"subjectWobble":false,"hookIntro":null,"cliffhanger":false},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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. 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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos/publish":{"post":{"operationId":"shared_videos_publish","summary":"Post a finished video (V3, Studio 2.0 or Character Explainer) 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 and a Character Explainer video 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. 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) or ce (a Character Explainer video).","type":"string","enum":["v3","studio","ce"]},"projectId":{"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Character Explainer video (session) 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"},"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","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"]},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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) or ce (a Character Explainer video).","type":"string","enum":["v3","studio","ce"]},"projectId":{"description":"The project id: a V3 project id, a Studio 2.0 project id, or a Character Explainer video (session) 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"},"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","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"video":{"type":"object","properties":{"product":{"type":"string","enum":["v3","studio","ce"]},"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}},"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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","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","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`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `plan_required`, `forbidden`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revision_conflict`, `idempotency_key_reused`, `idempotency_in_progress`, `confirmation_invalid`, `conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `daily_limit_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"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"}}}}}}}}