Name: aicut
Author: aicut

Returns the signed-in aicut account's token balance and plan tier. WHEN: before the first priced ask of a session, when the user asks what they have left, or after a generation fails for lack of tokens. top_up_url (the balance cannot pay for the cheapest generation, or a quote says sufficient_balance: false) is the ONLY link to give for adding tokens; never guess one. Prices: list_models, or

No parameter schema on file.

Returns the AI video, image and audio models this API can generate with: each model's exact parameters (names, allowed values, limits, defaults), the media inputs it takes and its pricing. WHEN: call this, NARROWED and never as the whole catalog, before the first generate_video, generate_image or generate_audio of a session: model ids cannot be guessed, nor can the resolutions, durations or

Parameter	Type	Required	Notes
type	string	no	Only one product: video, image or audio. Omit for all three.
model	string	no	Only the model with this exact id (for example kling-3.0).
query	string	no	Free text: the user's own words ('vertical product ad', '4k'). Words that match nothing are dropped and named in ignored_query_terms; the rest must all match (an AND).
tags	array	no	Tags every returned model must carry (an AND), e.g. ['video','vertical','reference-image']; tag_vocabulary rides on every answer and an unknown tag is a 400.
limit	integer	no	1-100. Omit to get every match (right once filtered); otherwise read has_more and total_matching.
cursor	string	no	The previous next_cursor. Send the SAME type / model / query / tags with it: different filters are a 400, not a restart.

Returns a step-by-step recipe as text: story-episode (an AI Video Story episode, end to end), starter-video, starter-image, starter-audio (a first generation), fake-text and image-story (write the script), niche-run (a niche from list_niches), talking-avatar (a picture speaks a script), motion-control (a picture copies a clip's motion). Read the recipe before the first call of

Parameter	Type	Required	Notes
name	string	yes	Which recipe.

Starts an AI video generation on the signed-in aicut account, puts the aicut card in front of the user and returns the new job's id immediately. It does NOT wait for the video. WHEN: the user asks for a video. Call list_models first if you have not this session (an unpublished combination is rejected). get_recipe starter-video has the first-video steps. CONSENT: a real person's picture only

Parameter	Type	Required	Notes
model	string	yes	Model id exactly as list_models returns it (for example kling-3.0). Use the one the user asked for; never substitute a cheaper model to save them tokens.
prompt	string	no	What the video should show. The model's prompt parameter in list_models gives its character limit.
aspect_ratio	string	no	One of the model's published aspect_ratios (for example 9:16).
resolution	string	no	One of the model's published options (for example 1080p); higher costs more. Only if the user asked; never to save tokens, never carried over.
duration	number	no	Seconds, one of the model's published durations; longer costs more. Only if the user asked; never to save tokens, never carried over.
audio	boolean	no	Sound on the video, on the models that support it (list_models says whether it costs extra). DEFAULTS TO FALSE: a model sold on native audio still renders SILENT unless you set it: set it when the u
start_image	string	no	Image URL to start the video from: a public https URL (aicut fetches and stores it) or an earlier generation's URL on this account.
end_image	string	no	Image URL the video should end on. Same rules as start_image.
reference_images	array	no	Image URLs for style or subject references, on the models that accept them. Same rules as start_image.
reference_videos	array	no	Reference video URLs, on the models that accept them: this account's own media or a public video (imported). Another account's is refused.
character_ids	array	no	Ids of this account's UPLOADED characters (kind: "uploaded" in list_characters, up to 20, in order of appearance). aicut first draws a start frame placing them (a flat 0.2 tokens, included in `est
scenes	array	no	A storyboard instead of one prompt: several scenes, each with its own prompt and duration; the provider returns ONE video. ONLY ON THE MODELS THAT PUBLISH IT (today kling-3.0): at most 5 scenes, eac
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

Returns the current state of one video generation: a SINGLE, IMMEDIATE read that waits for nothing. WHEN: only when you need one job's raw fields now (what it cost, whether it was refunded, why it failed). It is not how you wait (wait_for_generation is) and not how you show a video (the create already opened the card; show_generation brings back an earlier one). Do not poll it. When the user s

Parameter	Type	Required	Notes
id	string	yes	The job id returned by generate_video or generate_story_video (the documented way to read a story episode's stage); list_videos carries it too.

Deletes ONE video from the signed-in account's library: any of its own videos, in any state (finished, failed or still generating), exactly like the delete button in the web app. WHEN: the user asks to remove a video or tidy up after a failed one (a story episode whose writer failed, story.stage: "writing_failed", charged nothing and can simply be left). NO REFUND, and say so first when the user

Parameter	Type	Required	Notes
id	string	yes	The video's job id, as list_videos or generate_video returns it.

Returns the signed-in account's videos, newest first, one page at a time (pass cursor from the previous next_cursor while has_more is true). WHEN: the user asks what they have made, or you need a video from an earlier session. It is the whole library, including videos made in the web app and with products this API cannot create. THIS IS HOW YOU FIND A STORY EPISODE, and every story tool need

Parameter	Type	Required	Notes
limit	integer	no	How many to return, 1 to 100. Defaults to 20.
cursor	string	no	The previous response's next_cursor. Omit for the first page.
kind	string	no	Only videos of this kind: story_episode is an AI Video Story episode (the rows the story tools take an id from). Omit for the whole library.

Increases an existing image's resolution and returns the new job's id immediately (it does NOT wait). Same image, more pixels. WHEN: the user asks to upscale, enhance, sharpen or increase the resolution of a picture they have, including one an earlier generate_image returned. It is not how you change what is IN the picture (generate_image with the picture as a reference). WHICH MODEL (`upscale

Parameter	Type	Required	Notes
model	string	yes	Which upscaler. They differ in price by more than any other setting: use the one the user asked for. REQUIRED: if the user gave none, put your pick and its price in the priced ask; never one chosen to
source_image	string	yes	URL of the image to upscale. A URL from this account's generations or uploads, or a public https URL (imported first); another account's is refused. A PHOTO FROM THE USER'S OWN MACHINE QUALIFIES: uplo
upscale_factor	number	no	Times larger. topaz: 1, 2 or 4; seedvr: any whole number 1 to 10; recraft takes NONE and REFUSES the request if you send one. Default 2 on the two that take it. A result over the model's output limit
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

Takes a video and a description of what to change and generates the SAME clip with those changes applied (different characters, clothes, setting) while the camera move, timing, framing and the performers' motion stay as they were. Returns the new job's id immediately. WHEN: the user wants to restyle, recast or reskin footage they already have ('make the crowd elderly', 'put them all in suits', 'ma

Parameter	Type	Required	Notes
source_video	string	yes	URL of the video to edit, 3 to 10 seconds long. A URL from this account's generations or uploads, or a public https URL (imported first); another account's is refused.
prompt	string	yes	What to CHANGE about the clip: describe the replacement, not the whole scene (the camera, timing and motion are kept, so directions about them are wasted). Name what each thing in frame becomes.
resolution	string	yes	Output resolution; 1080p costs more per second. REQUIRED: use 720p unless the user asked for 1080p, and name the choice in the priced ask; never carried over from an earlier request.
reference_images	array	no	URLs of up to a few images to steer the result (a face, an outfit, a prop). Same URL rules as source_video. Sending this switches to kling-o3's references mode, which also accepts duration and `
duration	number	no	Output length in seconds; only meaningful with reference_images (otherwise the source clip's own length). Only if the user asked; never to save tokens, never carried over.
aspect_ratio	string	no	Output aspect ratio (for example 9:16); only meaningful with reference_images (otherwise inherited from the source clip). Only if the user asked; never to save tokens, never carried over.
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

Increases an existing video's resolution (2x, 3x or 4x) and returns the new job's id immediately. It does NOT wait for the result and does not change the content: same shot, more pixels. WHEN: the user asks to upscale, enhance, sharpen or increase the resolution of a video they already have. It is not how you make a video look different (that is a new generation). THE CARD: this call already opene

Parameter	Type	Required	Notes
source_video	string	yes	URL of the video to upscale. A URL from this account's generations or uploads, or a public https URL (imported first); another account's is refused.
upscale_factor	number	no	Times larger: 1, 2, 3 or 4 (default 2). A result over 7680px on either side is refused before anything is charged. Only if the user asked; never to save tokens, never carried over.
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

Generates a NEW segment that continues an existing video from its final frame and returns the new job's id immediately; the result is the original clip with the new segment joined on. WHEN: the user asks to extend, continue or lengthen a video, or wants to see what happens next in a clip they have. Call list_models first if you have not this session: model and the allowed aspect_ratio, `reso

Parameter	Type	Required	Notes
model	string	yes	Model id exactly as list_models returns it. Use the one the user asked for; never substitute a cheaper model to save them tokens.
source_video	string	yes	URL of the video to continue. A URL from this account's generations or uploads, or a public https URL (imported first); another account's is refused.
prompt	string	no	What should happen in the NEW segment.
aspect_ratio	string	yes	One of the model's published aspect_ratios. REQUIRED: the server does not guess it from the source clip and it changes the price on some models. Match the source clip's shape unless the user asked o
resolution	string	no	One of the model's published options; higher costs more. Only if the user asked; never to save tokens, never carried over.
duration	number	yes	Length of the NEW segment in seconds, one of the model's published durations; longer costs more. REQUIRED: if the user gave none, put your pick and its price in the priced ask; never one chosen to sav
audio	boolean	no	Generate audio for the new segment, on the models that support it (list_models says whether sound costs extra). IT DEFAULTS TO FALSE: the segment is SILENT unless you set it. Only if the user asked;
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

Takes a picture of a character and a reference video and generates a video of THAT character performing the reference's motion (a dance, a walk, a gesture). Returns the new job's id immediately. WHEN: the user wants their character to dance, copy a move or perform a clip's motion. The clip supplies the MOVEMENT only; the character comes entirely from the picture. CONSENT: a real person's picture o

Parameter	Type	Required	Notes
model	string	yes	kling-3.0-motion-control is the better and about 4x dearer one; kling-2.6-motion-control is the everyday choice. Ask the user rather than picking the expensive one for them.
character_image	string	yes	URL of the picture of the character to animate. A URL from this account's generations or uploads, or a public https URL (imported first); another account's is refused.
reference_video	string	yes	URL of the video whose motion to copy. A URL from this account's generations or uploads, or a public https URL (imported first); another account's is refused.
resolution	string	yes	Output resolution; 1080p costs more per second. REQUIRED: use 720p unless the user asked for 1080p, and name the choice in the priced ask; never carried over from an earlier request.
character_orientation	string	no	What the character picture is: video (default) for a full-body or moving subject, image for a still portrait (which lowers the reference clip's maximum to 10 seconds).
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

Takes a picture of a person and an audio file and generates a video of THAT person speaking or singing the audio, lip-synced. Returns the new job's id immediately; the result is exactly as long as the audio. WHEN: the user wants a talking avatar, a presenter or a voiceover on a face. The picture supplies the person; the audio supplies the performance AND the length. CONSENT: only a picture of the

Parameter	Type	Required	Notes
character_image	string	yes	URL of the picture of the person who should speak (a clear, front-facing portrait works best; see CONSENT). A URL from this account's generations or uploads, or a public https URL (imported first); an
source_audio	string	yes	The audio to lip-sync to: the id generate_audio returned, or its url. It must be audio generated on THIS account; an external audio url or a local file is not accepted.
resolution	string	yes	Output resolution; 1080p costs exactly twice 720p per second of audio. REQUIRED: use 720p unless the user asked for 1080p, and name the choice in the priced ask; never carried over from an earlier
prompt	string	no	Optional direction for the performance (a mood or manner). It does not change what is said: the words come from the audio.
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

OPENS A FILE PICKER RIGHT HERE, in this conversation: the user presses a button, chooses a video OR PHOTO from their own computer and watches it upload, and then it is on their aicut account for every tool. No link, nothing to paste. CALL IT IMMEDIATELY, WITHOUT ASKING ANYTHING FIRST, the moment the user refers to a video or image file on their machine ('upscale the clip in my Downloads', 'use the

No parameter schema on file.

Puts a VIDEO OR IMAGE FILE FROM THE USER'S OWN MACHINE onto their aicut account so the generation tools can use it (every other tool takes a URL). It returns an upload target in two forms, a ready-to-run curl_template for you and a browser_upload_url for the user; then you call confirm_upload. CANNOT RUN A SHELL COMMAND ON THE USER'S OWN MACHINE (claude.ai, ChatGPT, Claude Desktop, the mobil

Parameter	Type	Required	Notes
content_type	string	yes	The file's real type, taken from the file itself, not its name.
bytes	integer	yes	The file's real size in bytes, read off disk: signed as the hard limit. Ceiling: 50 MB for a video, 20 MB for an image.
file_name	string	no	The local file name, for your own bookkeeping; not stored.

Checks the file uploaded to an upload_media target and makes it usable. Returns the media url to pass to other tools, the file's size, its kind (video or image), its measured width and height and, for a video, duration_seconds. WHEN: right after the bytes moved (the curl printed a 2xx, or the user says they finished on the browser_upload_url page). It checks that the CONTENTS mat

Parameter	Type	Required	Notes
id	string	yes	The id upload_media returned for this file.

Generates an AI image on the signed-in aicut account and puts the aicut card in front of the user. It waits for the image server-side for as long as one request safely can (about 24 seconds), so it usually returns the finished image with its url directly. WHEN: the user asks for an image. Call list_models first if you have not this session (an unpublished combination is rejected). get_recipe

Parameter	Type	Required	Notes
model	string	yes	Model id exactly as list_models returns it (for example nano-banana-2). Use the one the user asked for; never substitute a cheaper model to save them tokens.
prompt	string	no	What the image should show. The model's prompt parameter in list_models gives its character limit.
aspect_ratio	string	no	One of the model's published aspect_ratios (for example 9:16).
resolution	string	no	One of the model's published options (for example 1k); higher costs more. Only if the user asked; never to save tokens, never carried over.
quality	string	no	Quality tier, on the models that publish a quality parameter; higher costs more. Only if the user asked; never to save tokens, never carried over.
images	array	no	Input image URLs to edit or use as references, on the models that accept them: public https URLs (aicut fetches and stores them) or earlier generations' URLs on this account.
wait	boolean	no	false returns the job id at once (no wait of about 24 seconds): for several images, start them all, then ONE wait_for_generation with ids. Default true.
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

Returns the current state of one image generation: a SINGLE, IMMEDIATE read that waits for nothing. WHEN: only when you need one job's raw fields now (what it cost, whether it was refunded, why it failed). It is not how you wait (wait_for_generation is) or show an image (generate_image already opened the card; show_generation brings back an earlier one). Do not poll it. status is queued,

Parameter	Type	Required	Notes
id	string	yes	The job id returned by generate_image.

Returns the signed-in account's images, newest first, one page at a time (pass cursor from the previous next_cursor while has_more is true). WHEN: the user asks what they have made, or you need an image from an earlier session, for example to pass its url into generate_video as a start frame. It is the whole library, including images made in the web app.

Parameter	Type	Required	Notes
limit	integer	no	How many to return, 1 to 100. Defaults to 20.
cursor	string	no	The previous response's next_cursor. Omit for the first page.

Starts an audio generation on the signed-in aicut account, puts the aicut card in front of the user and returns the new job's id immediately. It does NOT wait for the audio. One tool for all three kinds, chosen by the model you pass: spoken voice-over, music and sound effects. WHEN: the user asks for speech, a voice-over, music, a soundtrack or a sound effect. Call list_models with `type: "aud

Parameter	Type	Required	Notes
model	string	yes	Model id exactly as list_models returns it (elevenlabs-tts-v2 speech, elevenlabs-music music, elevenlabs-sfx sound effect); it decides which other arguments apply. Use the one the user asked f
text	string	no	Speech: the exact words to speak (priced PER CHARACTER: never padded or shortened to change the price). Sound effect: a description of the sound. Only if the user asked; never to save tokens, never ca
prompt	string	no	Music: a description of the track (mood, instruments, tempo). Speech and sound-effect models take text and reject this.
voice	string	no	Required by speech models. Get it from list_voices with provider: 'elevenlabs', usable_for: 'audio', limit: 100 (21 stock voices; without limit you see 20 and cannot tell). The user picks it fro
length_ms	number	no	Music length in whole milliseconds within the model's min/max; billed per started minute. An omitted length is quoted at a fallback price, so estimate_only with the exact value is the only accur
duration	number	no	Sound-effect length in seconds within the model's min/max; billed per second. An omitted length is quoted at a fallback price. Only if the user asked; never to save tokens, never carried over.
prompt_influence	number	no	Sound effects: how literally to follow the text (the model's min/max). Result only, not price.
stability	number	no	Speech: how steady the delivery is (lower more expressive, higher flatter). Result only, not price.
similarity_boost	number	no	Speech, elevenlabs-tts-v2 and -v4 only: how closely the delivery sticks to the voice. Result only.
style	number	no	Speech, elevenlabs-tts-v2 only: how far the speaker's own style is exaggerated. Result only.
speed	number	no	Speech, elevenlabs-tts-v2 only: speaking rate, 1 is normal. Result only.
force_instrumental	boolean	no	Music: no vocals. Result only, not price.
loop	boolean	no	Sound effects: loop seamlessly. Result only, not price.
estimate_only	boolean	no	Price only; creates nothing. The only accurate way to price audio (see COST).
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

Returns the current state of one audio generation: a SINGLE, IMMEDIATE read that waits for nothing. WHEN: only when you need one job's raw fields now (what it cost, whether it was refunded, why it failed). It is not how you wait (wait_for_generation is) or show a clip (generate_audio already opened the card; show_generation brings back an earlier one). Do not poll it. status is queued, `

Parameter	Type	Required	Notes
id	string	yes	The job id returned by generate_audio.

Returns the signed-in account's audio generations, newest first, one page at a time (pass cursor from the previous next_cursor while has_more is true). WHEN: the user asks what they have made, or you need a voice-over, track or sound effect from an earlier session. It is the account's top-level audio, including audio made in the web app; it excludes the clips other products generate INSIDE a

Parameter	Type	Required	Notes
limit	integer	no	How many to return, 1 to 100. Defaults to 20.
cursor	string	no	The previous response's next_cursor. Omit for the first page.

The WHOLE voice catalogue: every voice aicut can speak with, across ElevenLabs (platform stock AND this account's cloned and custom voices) and OpenAI. Free, instant. EVERY VOICE ID COMES FROM HERE: generate_audio's voice, generate_fake_text_video's voice_left / voice_right and generate_image_story's voice. Never invent one (it fails AFTER the job exists and is charged); `list_models

Parameter	Type	Required	Notes
provider	string	no	Restrict to one provider: elevenlabs (the live library, and the only provider generate_audio can use) or openai (8 voices). Omit for both.
usable_for	string	no	The door you are about to call: audio, fake_text or image_story. Every voice returned is one that tool accepts. openai with audio is a 400 naming the provider that does serve it.
limit	integer	no	1-100, default 20 (a shortlist). The full library never fits in one result, whatever you pass.
cursor	string	no	The previous next_cursor. Send the SAME provider / usable_for with it: different filters are a 400, not a restart.

Waits up to 15 seconds for an aicut generation to reach a terminal state, WITHOUT opening a card, and returns the compact status. SEVERAL ITEMS: quote each, ask once with the total, start them all (images with wait: false, distinct idempotency_keys or none), then make ONE call with ids (1 to 6 of {id, media}) instead of id and media. terminal is always present: true means nothing f

Parameter	Type	Required	Notes
id	string	no	A job id from a generate_* tool or transform, or an episode id from generate_story_video (media video).
media	string	no	Which kind of generation the id belongs to: video (a generate_video job, any video transform: upscale_video, extend_video, edit_video, motion_control, generate_lipsync, and a story rende
ids	array	no	Several jobs at once (see SEVERAL ITEMS), instead of id and media.

Shows an EARLIER aicut generation to the user again, in the aicut card: the video, image or audio itself, with what it cost and when it was made. WHEN: the user asks to see something they already have (from earlier in this conversation, or found with list_videos / list_images / list_audio): that is its only job. Each generate_* already put the card up on the call that started the job, so c

Parameter	Type	Required	Notes
id	string	yes	A job id from a generate_* tool or transform, or an episode id from generate_story_video (media video).
media	string	yes	Which kind of generation the id belongs to: video (a generate_video job, any video transform: upscale_video, extend_video, edit_video, motion_control, generate_lipsync, and a story rende

Starts an AI analysis of an existing video and returns the new analysis's id immediately (it does NOT wait). It reads the video and describes it in detail (what happens, who is in it, the on-screen text, the pacing and cuts) as free-form text, plus the platform's own metadata (title, author, view count) when it has any. It generates nothing: use generate_video for that. WHEN: the user wants to u

Parameter	Type	Required	Notes
url	string	yes	The video to analyse: a public YouTube, TikTok or Instagram video url, or the url of a video this account uploaded to aicut. Pass the url the user gave you, unchanged: do not rewrite it, strip it to a
start_seconds	number	no	Where to start analysing, in seconds (default: the beginning). Use it when the user pointed at a moment.
end_seconds	number	no	Where to stop, in seconds: at most 128 seconds after start_seconds, which is also the default, so a longer video is analysed in a window and a wider span is rejected rather than trimmed. Cover a lon
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

Returns the current state of one video analysis on the signed-in account, and its result once finished. WHEN: after analyze_video; poll every 5-10 seconds until status is succeeded or failed. While it is not terminal the response carries poll_after_seconds: wait that long rather than picking your own interval. TIMING: an analysis usually finishes in under a minute and can take a few minu

Parameter	Type	Required	Notes
id	string	yes	The analysis id returned by analyze_video.

Returns the signed-in account's video analyses, newest first, one page at a time (pass cursor from the previous next_cursor while has_more is true). WHEN: the user asks what they have analysed, or before starting a new one (an analysis of the same video and window may already exist). It includes analyses started in the web app and TRANSCRIPTS (analysis.format: "text" rather than `"markdown

Parameter	Type	Required	Notes
limit	integer	no	How many to return, 1 to 100. Defaults to 20.
cursor	string	no	The previous response's next_cursor. Omit for the first page.

Returns the characters saved on this aicut account, newest first, one page at a time: kind: "uploaded" entries the user made from their own photos and kind: "cast_member" entries generated as AI Video Story cast. Each carries an id, a display name, a portrait image_url where one exists and, for cast members, the visual world. Read-only: it creates nothing and spends nothing. WHEN: the user

Parameter	Type	Required	Notes
limit	integer	no	How many to return, 1 to 100. Defaults to 50.
cursor	string	no	The previous response's next_cursor. Omit for the first page.

Lists aicut's AI Video Story series (niches): episodic short-video formats that generate a whole multi-scene episode from one idea. BROWSING IS browse_series' JOB: when the USER is choosing a series ('what series do you have'), call browse_series FIRST (a series is chosen BY EYE). THIS TOOL IS THE DATA READ behind that choice (prices, the duration ladder) and the fallback with no cards. Never

Parameter	Type	Required	Notes
series_id	string	no	A series id from the compact catalog: returns that ONE series with every field a quote or create needs. Omit for the compact catalog.
video_model	string	no	The model you intend to create on (the series' defaults.video_model unless the user named one): only its duration ladder comes back. Omit only to compare models. Needs series_id; a model the serie

Returns ONE series' CURATED preset ideas (the authored cards the webapp shows on its idea step). Free, instant, creates nothing. THIS IS NOT THE DEFAULT WAY TO GET AN IDEA: invent three of your own, one line each, and sharpen them with the user in chat; call this only when the user asks what the SERIES itself suggests ('show me the ones from the app'). Then offer at most 3, one line each, as the s

Parameter	Type	Required	Notes
series_id	string	yes	The series id, exactly as list_series returns it.

Lists aicut's trend-template niches: one-shot video formats made from a few answers (and sometimes a picture), each at one price. AI Video Story series are list_series, not these. WITHOUT slug: the cards (slug, name, description, suits, not_for, price, agent_supported). Shortlist 3-5 that fit, saying what each makes and what it is NOT for; never dump the list. WITH slug: that O

Parameter	Type	Required	Notes
slug	string	no	A niche's slug from the list: returns that ONE niche in full. Omit for the cards.

Runs ONE niche on the signed-in account: starts the video, puts the aicut card in front of the user and returns the new job's id immediately. It does NOT wait for the video. WHEN: the user wants one of the formats list_niches lists. Read that niche in full first: slug and revision come from it, values answer its text and select inputs by key, media fills its image inputs. A setting you

Parameter	Type	Required	Notes
slug	string	yes	The niche's slug, from list_niches.
revision	string	yes	The revision of the niche as you read it (list_niches with slug).
values	object	no	Answers to the text and select inputs, by input key: the user's own words, or a select's options value (own words only where allow_custom).
model	string	no	A settings.options.models value. Only if the user asked; never to save tokens, never carried over.
aspect_ratio	string	no	A settings.options.aspect_ratios value. Only if the user asked; never to save tokens, never carried over.
duration_seconds	number	no	One of the niche's settings.options.durations_seconds; longer costs more. Only if the user asked; never to save tokens, never carried over.
resolution	string	no	One of the niche's settings.options.resolutions; higher costs more. Only if the user asked; never to save tokens, never carried over.
audio	boolean	no	Sound on the video, where settings.options.audio_selectable is true. Only if the user asked; never to save tokens, never carried over.
media	array	no	One entry per picked image.
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

PUTS THE SERIES CATALOGUE ON SCREEN as a grid of previews the user can look at and pick from, right in this conversation: each tile shows that series' 9:16 still, plays its demo clip in place, and choosing one (select a tile, then confirm) posts the choice into the chat as a message from the user. Free, instant, spends nothing. It is the answer to 'what series are there' on a client that renders c

No parameter schema on file.

Lists the AI-generated short-form videos aicut tracks as TRENDS: real TikTok videos, each in a published trend cluster (a niche: object-head drama, fruit drama, talking objects). It is aicut's own vetted /trends feed. Free, instant, creates nothing. EACH ROW: id (for get_recreate_brief), url, caption, hashtags, the engagement counts, outlier_ratio (how far the video beat its channel's

Parameter	Type	Required	Notes
cluster_id	string	no	Narrow to one trend cluster: a row's cluster_id.
language	string	no	Spoken-language code, e.g. en or de. Omit for every language.
days	integer	no	Only videos published within this many days. Omit or 0 for the whole tracked window (older than 90 days is already dropped).
dialogue	string	no	Speech filter. Defaults to dialogue, which HIDES confirmed music-only / sfx-only / silent videos; any includes them, no_dialogue returns only those.
breakout	boolean	no	True for only new-channel breakout videos.
sort	string	no	trending (views, default), newest or ratio (outlier ratio).
limit	integer	no	How many to return, 1 to 50. Defaults to 20.
page	integer	no	1-based page number. Defaults to 1.

For making a NEW, original video in a trend's format, never a copy of it, its script or its characters: returns ONE trend video's public row, the NICHE it belongs to (the published cluster, with the premise a human wrote), a written brief you can hand to a create call as its idea, and next_steps. Free, instant, creates nothing. IT DOES NOT TELL YOU WHICH SERIES TO USE: series.selected is alw

Parameter	Type	Required	Notes
trend_id	string	yes	A trend video's id from a list_trends row. Not a url.

Writes the CAST for an AI Video Story series (named characters, each with a role and a one-line description) as a DRAFT for the user to read. FREE: it spends no tokens, generates no portraits and saves nothing to the character library. WHEN: as soon as the episode idea is settled, on a series whose cast.required is true (or whose user wants custom characters). Do NOT ask permission: it costs not

Parameter	Type	Required	Notes
series_id	string	yes	The series id, exactly as list_series returns it.
idea	string	no	The episode idea the cast should serve, one short paragraph: pass the user's idea whenever there is one. Only when omitted does the writer author a logline.
language	string	no	Omit unless the user asked for another language (the series' defaults.language is used). Pass the SAME language to generate_story_video.
world	string	no	The visual world for the cast (fruits, humans, animals). Unset lets the writer pick.

BUYS the portraits for a cast draft: one image generation per member that still needs a face, at the chosen image model's rate, then saves every member to the user's character library. The cast's paid step (the webapp's 'Generate cast' button). WHEN: the user has READ the draft from generate_cast, accepted it, and said go to the price. Take the figures from the draft's own portrait_models (`pe

Parameter	Type	Required	Notes
draft_id	string	yes	The draft_id from generate_cast.
portrait_model	string	no	One of the draft's portrait_models ids. It draws the faces: name it with the price (see OFFER THE IMAGE MODEL), then omit it if the user has no preference (default: true is what the series is tune
estimate_only	boolean	no	Price only; creates nothing.

Redraws ONE cast member's portrait (the same character, a new image) and attaches it to that member: ONE image generation, not a new cast. WHEN: the user dislikes a member's face, or a portrait FAILED (the story create refuses a cast with a failed portrait and names this). character_id is the member's id from generate_cast_portraits or list_characters (kind cast_member). It draws the SAM

Parameter	Type	Required	Notes
character_id	string	yes	The cast member's library id: id on a generate_cast_portraits member or on a list_characters entry of kind cast_member.
image_model	string	no	Image model: the member's OWN image_model from generate_cast_portraits (matches the cast and its price). Omitted, the platform default portrait model is used: maybe a different look and price.
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

CHANGES ONE cast member into a different character: you pass a new one-line visual description, aicut rewrites the member's stored look from it and draws ONE new portrait (the rest of the roster is untouched). It is the tool for 'make the husband smaller and a white strawberry': NOT regenerate_cast_portrait (the SAME character again), nor a new generate_cast (it re-authors every member and re-

Parameter	Type	Required	Notes
character_id	string	yes	The cast member's library id: id on a generate_cast_portraits member or on a list_characters entry of kind cast_member.
description	string	yes	What this character looks like NOW: one whole line of plain visual English (see THE DESCRIPTION). Not a diff or an image prompt: anything omitted is lost.
image_model	string	no	Image model: the member's OWN image_model from generate_cast_portraits (matches the cast and its price). Omitted, the platform default portrait model is used: maybe a different look and price.
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

Starts an AI Video Story EPISODE (stage 1 of 3): the engine writes the multi-scene episode from your idea, draws the OPENING PICTURE OF EVERY SCENE, and PARKS for the user to look at them before any video generates. Returns immediately. Say 'the opening picture of each scene' to the user, never 'start frames' or 'frames review' (field names). WHEN: the series is picked and its FULL entry fetched (

Parameter	Type	Required	Notes
series_id	string	yes	The series id, exactly as list_series returns it.
idea	string	yes	The episode idea: one short paragraph of plain prose, no scene lists, shot directions or image prompts.
duration_seconds	number	yes	Episode length in SECONDS: one of the chosen model's published durations.options[].seconds on the series' FULL list_series entry (durations.default_seconds if the user has no preference). Never
video_model	string	yes	One of the series' pricing.video_models ids: its defaults.video_model unless the user names one. It decides which duration ladder applies, so pick it before the length.
start_frame_model	string	no	Image model for the opening pictures (pricing.start_frame_models). Omit for the series' defaults.start_frame_model, which frames_tokens is priced at; any other needs a fresh estimate_only.
language	string	no	Omit unless the user asked for another language: the series' defaults.language is used.
aspect_ratio	string	no	9:16 (default) or 16:9.
cast_member_ids	array	no	Approved cast member ids from generate_cast_portraits (or list_characters, kind cast_member), in roster order. Required when cast.required, forbidden when cast.writer_owned.
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

Redraws ONE scene's opening picture of an episode parked at frames review (story.stage: "frames_review"), from the scene's own text, cast and continuity references. There is no prompt argument. WHEN: the user dislikes THE PICTURE itself (hands, framing, a face that came out wrong, a failed lane). scene_index is that frame's zero-based scene_index in get_video's story.frames. If what HAPP

Parameter	Type	Required	Notes
video_id	string	yes	The episode's job id from generate_story_video.
scene_index	integer	yes	The zero-based scene index exactly as get_video's story.frames lists it (users count from ONE: 'redraw scene 2' is the SECOND frame).
cast_member_ids	array	no	Cast member library ids for this redraw. Omit for the scene's own cast; [] for no characters.
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

CHANGES WHAT HAPPENS IN ONE SCENE of an episode parked at frames review and redraws its opening picture from the change. You pass a PLAIN SENTENCE ('the kid should look super sad', 'move it outside at night'); aicut rewrites that scene's setting / people / action text from it and draws the new picture: ONE image generation. The change STICKS (the scene video made at fire uses it). It is the tool f

Parameter	Type	Required	Notes
video_id	string	yes	The episode's job id from generate_story_video.
scene_index	integer	yes	The zero-based scene index exactly as get_video's story.frames lists it (users count from ONE: 'change scene 2' is the SECOND frame).
change	string	yes	What should be different, as ONE plain sentence in the user's own words ('the kid should look super sad'). It must be VISIBLE (setting, action, who is in frame): a sentence only about what somebody SA
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

REMOVES one scene from an AI Video Story episode parked at frames review. The scene's VIDEO is never generated or charged, so the fire quote and charge drop by exactly that scene's price. Free: it spends nothing (the scene's start frame was already charged at create and is not given back). WHEN: the user looked at the frames and wants a scene GONE rather than redrawn, before fire_story_video. `s

Parameter	Type	Required	Notes
video_id	string	yes	The episode's job id from generate_story_video.
scene_index	integer	yes	The zero-based scene index exactly as get_video's story.frames lists it.

FIRES a parked AI Video Story episode (stage 2 of 3): generates every kept scene's VIDEO from its reviewed picture. The paid step after review; nothing renders yet. WHEN: story.stage is frames_review, the user has looked at the pictures and any redraws are done; cut scenes first with remove_story_scene (a removed scene's video is never generated or charged). Always estimate_only: true firs

Parameter	Type	Required	Notes
video_id	string	yes	The episode's job id from generate_story_video.
auto_render	boolean	no	Arm the final render: it starts by itself when the scenes finish and charges then (the quote adds render_estimated_tokens). Only with the user's approval of that charge.
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Ignored by this door: a second fire is refused already_fired.

RENDERS an AI Video Story episode into its final delivered file (stage 3 of 3), after the scene videos are done. It is composed SERVER-side from the stored episode (scenes, captions, music, title card, watermark policy); you pass only the episode id. WHEN: get_video shows succeeded or story.stage: "ready_to_render" (an episode edited in the web editor renders with those edits; a later render

Parameter	Type	Required	Notes
video_id	string	yes	The episode's job id from generate_story_video.
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

CREATES a fake-text video: a phone chat conversation that types itself out over a gameplay or green-screen background, every line read aloud in the voice you pick for that side. YOU WRITE THE SCRIPT: there is no writer behind this endpoint, and the messages array you send IS the conversation, in that order, one {text, from} per chat bubble (get_recipe fake-text has the format advice and a

Parameter	Type	Required	Notes
messages	array	yes	The conversation, in order, one entry per chat bubble. This is the script, and you write it.
contact_name	string	yes	The name at the top of the phone screen: who the owner is texting ('Mom', 'Jake ❤️').
template	string	no	The chat app skin. Defaults to imessage.
voice_provider_left	string	no	Who reads the LEFT side. elevenlabs is the web app's default, openai is cheaper and covers every language with the same eight voices. Defaults to openai. IT CHANGES THE PRICE: ElevenLabs costs a
voice_left	string	no	The voice for the LEFT side. Pick two different voices so the two people sound different (there is no silent option). The voice id for this side, in the provider named by voice_provider_* (omit for
voice_speed_left	number	no	The LEFT side's reading speed. 1 normal (default), 1.15 fast, 1.25 very fast. Faster makes the video shorter and costs nothing extra (the price is per character).
voice_provider_right	string	no	Who reads the RIGHT side: same choices and price rule as voice_provider_left.
voice_right	string	no	The voice for the RIGHT side: same rules as voice_left.
voice_speed_right		no	The RIGHT side's reading speed: as voice_speed_left.
language	string	no	The language the conversation is written in, by name ('English', 'German'); default English. Write messages in it too: this labels the script, it does not translate it.
background	string	no	random (a gameplay clip, the usual choice) or greenscreen (plain, to key out later). Default random.
aspect_ratio	string	no	Defaults to 9:16, the vertical shape every short-form platform wants.
notification_sounds	boolean	no	Play a message tone as each bubble arrives. Defaults to true.
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

CREATES an AI image story: a narrated script turned into a sequence of AI-generated images, read aloud with captions over it. Suited to facts, history, horror, storytime and explainers. YOU WRITE THE SCRIPT, AND ONLY THE SCRIPT: the text you send is the narration that is spoken, verbatim, in that order (get_recipe image-story has the writing advice and a worked example). Show it to the user

Parameter	Type	Required	Notes
text	string	yes	The narration script in plain prose: what the voice says, start to finish. No scene markers, image directions or speaker labels; aicut cuts it into scenes and writes every image itself.
language	string	no	The language text is written in, by name; default English. Naming another language makes aicut translate the script, which changes its length and the price.
image_model	string	no	The look of the images; default zit-realism (photoreal, cheapest). zit-lora-* and zit-comic are illustrated looks at the same price, flux-klein* cost more, gpt-image-2.5 is the priciest: quo
image_resolution	string	no	Defaults to standard. high selects the model's high-resolution price row (for some models both rows cost the same).
style_id	string	no	An authored look from list_image_story_styles. It forces the expensive edit-capable image model, so re-quote. Omit for aicut's default photorealistic look.
voice_provider	string	no	Which voice service reads the narration. openai (the default) or elevenlabs. The two voice services are priced differently, so call estimate_only again after changing it.
voice	string	no	The narrator's voice. The voice id, in the provider named by voice_provider; omit for that provider's default narrator. openai: alloy, ash, ballad, coral, echo, sage, shimmer, verse (ash reads dee
seconds_per_image	number	no	How long each image stays on screen; default 3. THE MAIN PRICE LEVER: 5 buys roughly 40% fewer images than 3 for the same script, 2 buys 50% more.
caption_style	string	no	How the burned-in captions look; default karaoke; none turns them off.
caption_position	string	no	Where the captions sit; default bottom.
aspect_ratio	string	no	Defaults to 9:16, the vertical shape every short-form platform wants.
sound_effects	boolean	no	An ambient sound effect per scene. Defaults to false, and it ADDS to the price by the video's length: quote it.
transition_sounds	boolean	no	A whoosh between scenes. Defaults to false; free.
transition_effects	boolean	no	A visual slide between scenes. Defaults to false; free.
estimate_only	boolean	no	Price only; creates nothing.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

Lists aicut's authored image-story STYLES: named looks (a character, a rendering treatment, an art direction) that every scene of the video is drawn in. Free, instant, creates nothing. OPTIONAL, NOT THE DEFAULT: most image stories use aicut's ordinary photorealistic look, which is also the cheapest; call this when the user asks what looks exist or wants a consistent stylised world. IT CHANGES THE

No parameter schema on file.

Returns the social accounts this aicut user has connected for publishing, with the id prepare_post takes, plus connect_url. WHEN: before any posting attempt, and whenever the user asks where they can post. Each entry carries its platform (tiktok, youtube or instagram) and schedule_custody (aicut_scheduler: a scheduled post waits in aicut; platform, i.e. YouTube: the video is uploaded a

No parameter schema on file.

Puts a video NOT made on aicut (an upload, or a public https MP4/MOV link) on this account as a finished video; returns the id for prepare_post. Free. A local file: upload it, pass the confirm_upload url. A link costs one ingest slot. Only import what the user may post. IDEMPOTENCY: a reused idempotency_key REPLAYS the first job whatever the settings: never reuse one for a new generation (

Parameter	Type	Required	Notes
url	string	yes	The upload url or https link.
idempotency_key	string	no	Retry-safety key (IDEMPOTENCY).

Stages a post of one of this account's finished videos to one of its connected TikTok, YouTube or Instagram accounts and returns the post id publish_post takes. NOTHING IS PUBLISHED BY THIS CALL. WHEN: after list_social_accounts gave you an account id and you have a finished video's id (list_videos / get_video, status succeeded). AN AI VIDEO STORY EPISODE MUST BE RENDERED FIRST: it rep

Parameter	Type	Required	Notes
platform	string	yes	The platform to post to; it must match the platform of the account id (the platforms number accounts independently).
account_id	integer	yes	The connected account's id from list_social_accounts.
video_id	string	yes	The id of a FINISHED (episode: RENDERED) video on this account, or an import_video id.
caption	string	yes	The post text exactly as it should appear. TikTok and Instagram: up to 2200 characters. YouTube: the DESCRIPTION, up to 5000 (the title is title).
privacy_level	string	no	TikTok: PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR or SELF_ONLY, one of account_limits.privacy_level_options: ask the user. YouTube: public, unlisted or private. Required on both
title	string	no	YouTube only, and required there: the video title, up to 100 characters.
tags	array	no	YouTube only: up to 30 tags, 500 characters in total across all of them.
category_id	string	no	YouTube only: the category id. Defaults to 24 (Entertainment).
schedule_at	string	no	ISO-8601 time to publish at, at least 10 minutes ahead. Omit to publish when publish_post is called.
allow_comments	boolean	no	TikTok only. Allow comments. Defaults to true.
allow_duet	boolean	no	TikTok only. Allow duets. Defaults to true.
allow_stitch	boolean	no	TikTok only. Allow stitches. Defaults to true.
is_your_brand	boolean	no	TikTok disclosure: this post promotes the user's own business. Defaults to false; set it only if the user said so.
is_branded_content	boolean	no	TikTok disclosure: this post is a paid partnership. Defaults to false; set it only if the user said so.

Sends a post staged by prepare_post, or schedules it. Irreversible: the post goes out under the user's own name and cannot be taken down from aicut. It is for a post the user has confirmed: either in chat, after a question that named the account, the text, the visibility and any scheduled time (a bare 'yes' confirms only when that question about this post was the message immediately before it),

Parameter	Type	Required	Notes
post_id	string	yes	The id returned by prepare_post.
schedule_at	string/null	no	ISO-8601 time to publish at, at least 10 minutes ahead; overrides what prepare_post recorded. Null sends the post now. Omit to keep the prepared time.

Returns what the PLATFORM says happened to a post, plus post_id once it is live and fail_reason when it is not. Statuses: prepared (staged, nothing sent), scheduled (due at scheduled_at; schedule_custody says whether aicut or the platform holds it), submitted (handed to aicut's YouTube or Instagram poster, nothing confirmed), publishing (TikTok took the job and is fetching the file

Parameter	Type	Required	Notes
post_id	string	yes	The id returned by prepare_post.

OPENS THE PUBLISH CARD RIGHT HERE for a post prepare_post has already staged: the user watches the actual video, sees the destination account, edits the caption, picks the visibility, sets the commercial disclosure themselves, ticks a box saying they want it posted and confirms twice. NOTHING IS PUBLISHED BY THIS CALL OR BY THE CARD. CALL IT IMMEDIATELY AFTER prepare_post ON ANY CLIENT THAT RE

Parameter	Type	Required	Notes
post_id	string	yes	The id prepare_post returned; the card reads the post back from it.

Where are you running it?

Tool surface

Release history

aicut MCP

What it does

Quickstart

Where are you running it?

Tool surface

What counts against your monthly calls

Release history

See also