Astorie

Joins, trims, speeds up/slows down or mutes video clips into ONE new video in an Astorie project. Free: no credits. Each clip is a video node of the project (node_id) or a video url stored in Astorie (import_video / upload_video other videos first). start/end are seconds into that clip's own video; a negative value counts back from its end (start -5 keeps the last 5 s, end -5 cuts the last 5 s off), measured on the actual file, so you never need its length. Clips play in the order given. With target_duration_sec, a longer result has its END cut to fit: the last clip is shortened, or dropped when the cut is longer than it and the clip before it shortened. Without width/height/fps the result matches the first clip's orientation; other aspect ratios are letterboxed. Adds a new video node linked from the source nodes and returns its node_id right away, with a job_id; if it is still running, get_job / jobs_wait return the result. To edit a part of a video, first cut it with edit_video (one clip with start/end), wait for it (jobs_wait), then call generate_video with a video-edit model and reference_node_ids=[that node_id]. Call when the user named this edit or picked it in edit_options; when they already named it, do not show edit_options first.

edit_video

Rewrites a short prompt into a richer one for an image, video or audio generation, the way the canvas Enhance button does. Free: no credits. Show the user the result before generating with it.

enhance_prompt

Saves one frame of a video as a new image node beside it: the first, middle or last frame, or the frame at at_sec seconds. Free: no credits. Use the last frame as the start frame of the next shot to chain videos.

extract_frame

Used by the Astorie upload card: checks the uploaded file and returns its url.

finish_image_upload

Used by the Astorie gallery card's Load more: the next page of the same view.

gallery_page

Turns one image into a 3D model (GLB) in an Astorie project using the user's credits (workspace credits for a workspace project). Adds a new 3D node and returns a job_id; call get_job for the GLB url when it finishes (usually 1–5 minutes). list_models lists the 3D models and the credits each costs (quote prices one too): tell the user the cost before calling.

generate_3d

Generates audio in an Astorie project using the user's credits (workspace credits for a workspace project) and adds it as a new audio node. kind picks what to make and its default model: speech (text, optional voice), dialogue (lines: [{ text, voice }]), music (lyrics + text as the style/genre), sound_effect (text describing the sound, optional duration_sec; or a video-to-audio model with video_url / video_node_id), voice_design (voice_description + text as preview lines; the designed voice id then works as a voice for the minimax-speech models). list_models (audio section) names the models and the default per kind; list_voices their voices. Waits up to ~25 s; if not finished, returns a job_id for get_job. The result states the credits it cost. Every result carries project_id and node_id — reuse the project_id for the rest of the conversation.

generate_audio

Generates an image in an Astorie project using the user's credits (workspace credits for a workspace project). Adds a new image node, or regenerates node_id. Waits up to ~25 s; if not finished, returns a job_id for get_job. To edit an image with a prompt, pass it in reference_images (or its node in reference_node_ids) and describe the change; list_models names the edit models. Only when the user asked for a new generation or a prompt edit: for "improve/edit this image" without a named edit, call edit_options first. The result states the credits it cost. Before a batch of more than 4 images, call quote and confirm the total with the user. Every result carries project_id and node_id — reuse the project_id for the rest of the conversation.

generate_image

Starts up to 8 image generations at once (e.g. variations), all in one project, using the user's credits. FIRST call quote with the same model and options and quantity = the number of prompts, and confirm the total with the user when it is more than 4. Returns job_ids immediately without waiting; then call jobs_wait ONCE with all of them. Items it could not start are returned as not_started with the reason; to finish them, call again with the SAME full prompt list and the same request_id (started items replay). Without project_id a new project is created; reuse the returned project_id afterwards.

generate_image_batch

Starts a video generation in an Astorie project using the user's credits (workspace credits for a workspace project). Videos are expensive: FIRST call quote with the same model and options, tell the user the credit cost and wait for their go-ahead. Adds a new video node, or regenerates node_id. Returns a job_id right away; videos take 1–10 minutes — poll with get_job. Every result carries project_id and node_id — reuse the project_id for the rest of the conversation.

generate_video

Starts up to 8 video generations at once, all in one project, using the user's credits. Videos are expensive: FIRST call quote with the same model and options and quantity = the number of prompts, tell the user the total and wait for their go-ahead. Returns job_ids immediately; videos take 1–10 minutes — call jobs_wait with all of them (repeat for those still running). Items it could not start are returned as not_started with the reason; to finish them, call again with the SAME full prompt list and the same request_id (started items replay).

generate_video_batch

Status of an analyze_video run. While running: the current step. When succeeded: title, summary, the shot list (times, shot size, camera movement, description) and the screenplay. Poll about every 30 seconds; a run takes one to a few minutes.

get_video_analysis

Returns the user's remaining personal Astorie credits. For a team workspace's shared balance, use get_workspace_credits with its id from list_workspaces.

get_balance

Lists the past outputs of one node of a project (every generation it made, newest first), like the history panel on the canvas.

get_node_history

Summarises a project's canvas: each node's id, type, prompt, model, latest output URLs and the nodes it references (up to 60 nodes). Use node ids with generate_* (node_id to regenerate, reference_node_ids to reuse outputs).

get_project

A workspace's shared credit balance for its owner or an admin: monthly quota used and remaining, wallet credits, and when the quota resets. Workspace credits are separate from the personal credits get_balance reports. Members without the admin role are refused.

get_workspace_credits

For a workspace owner or admin: every member with their credits spent, refunded and net over the last `days` days (UTC), plus each member's current spending cap and how much of it is used. Use it to answer "who spent what" and to find the member user_id a cap change needs. Owners or admins only.

get_workspace_usage

Copies an audio file into Astorie so it can be used, e.g. as the audio_url of lipsync or on a canvas: a public https url, and/or (in ChatGPT) the audio the user attached in this chat, passed as files. MP3, WAV, M4A, OGG, FLAC or WebM, up to 100 MB.

import_audio

Copies images into Astorie and places each on a project canvas as an image node: a public https url, and/or (in ChatGPT) the images the user attached in this chat, passed as files. Free. Returns project_id and node_ids to edit them or use them as references. In Claude, chat attachments cannot be passed: call upload_image instead.

import_image

Copies a video into Astorie so it can be edited, extended or used as a reference video: a public https url, and/or (in ChatGPT) the video the user attached in this chat, passed as files. MP4 or MOV, under 256 MB. In Claude, chat attachments cannot be passed: call upload_video instead.

import_video

Makes the person in a video of an Astorie project speak an audio track, like the canvas Lipsync tool. Video: node_id or url; audio: audio_node_id (an audio node of the project) or audio_url. model: fal-ai/sync-lipsync/v2/pro, fal-ai/pixverse/lipsync, fal-ai/kling-video/lipsync/audio-to-video or creatify/lipsync; omit it for the default. sync_mode (cut_off, loop, bounce, silence, remap) handles audio longer or shorter than the video. Priced per second of video. Spends credits like the same tool on the Astorie canvas (quote does not price it; tell the user it costs credits, per second for videos). Adds a new node linked from the source and returns its node_id with a job_id right away; get_job / jobs_wait return the result if it is still running. Call when the user named this edit or picked it in edit_options; when they already named it, do not show edit_options first.

lipsync

Lists the image, video, audio and 3D (generate_3d) models available through Astorie, with their supported options. Audio models (for generate_audio) are listed under audio with the kinds they make and the default per kind; list_voices has their voices. A model marked requires_image needs at least one reference image (for an edit model, the image to edit); requires_video needs one video in reference_videos; requires_marketing needs the marketing argument. Models marked studio take presets or a template: call list_studio_options.

list_models

Lists what Astorie's two Studios offer this account. Astorie Director (lca-image, lca-video): every preset by kind — world, look, movement, speed, lens, palette — with the modes (image / video) each applies to, plus the user's saved color palettes. Astorie Ads (marketing-studio-video): the templates with their duration ranges, and the user's saved products (with their facts), people, voices and uploads. Call it before using either Studio and pass the slugs to generate_image / generate_video.

list_studio_options

Lists credit usage, newest first: what each generation cost, refunds and credits added, like the Usage page. Personal by default; pass workspace_id (from list_workspaces) for a workspace's log (owners and admins only). category: all, image, video, audio, threed or others. Pass next_cursor back as cursor for the next page.

list_transactions

Lists the user's Astorie projects (personal and workspaces they belong to), newest first. Use it when the user refers to an existing project.

list_projects

Lists the newest (up to 10) files the user uploaded or imported into Astorie in the last hour (upload_image / upload_video card, import_image, import_video), newest first, with their urls. Call it only when the user says they uploaded in the card and their message carries no urls and the card did not put them in your context; urls from the card always win (this list can include older files). Pass image urls in reference_images (or as Astorie Ads product_image / person_image) and video urls in reference_videos.

list_uploads

Lists the preset voices of the speech and dialogue audio models: name, voice_id (pass it as generate_audio voice, or a line's voice), model, and a preview_url to listen to where the provider publishes one. Pass model to list one model's voices.

list_voices

Lists where the user's projects live: their personal space and every workspace they belong to, each with its folders. Use the ids with create_project (to create in a workspace or folder) and list_projects (to find projects in one). A folder the user wants that is not listed can be made with create_folder.

list_workspaces

Moves a project the user manages into another folder of the same space (personal or its workspace), or out of any folder. Folder ids come from list_workspaces. A project cannot be moved to a different workspace. If the move changes access, first show the returned preview and ask the user to confirm.

move_project

Step 1 of 2 to change a member's spending cap in a workspace (owner or admin only). Returns the member, their current cap and usage, the proposed cap and the billing cycle it applies to, with a confirmation_token. Show the preview to the user and call set_member_credit_limit with the token only after they explicitly agree. Nothing changes until then. Pass limit_credits for a cap, or remove_limit: true to lift the cap. Resolve the member's user_id with get_workspace_usage first; never guess from a name.

preview_member_credit_limit

Returns exactly how many credits generate_image / generate_video / generate_audio / generate_3d would charge for these options in this project (personal or workspace credits), without generating or charging anything. Call it and confirm with the user before any video, before a batch of more than 4 images, and whenever the user asks what something costs. A requires_image model can be priced before the image is chosen: reference_images may be omitted here. It is the price IF the generation is accepted: submit can still refuse it (e.g. no free capacity or insufficient credits).

quote

Used by the Astorie batch result view to refresh several running generations. Returns immediately.

poll_jobs

Used by the Astorie result view to refresh a running generation. Returns immediately.

poll_job

Changes the lighting of an image of an Astorie project (or an image url), like the canvas Relight tool. prompt describes the light (e.g. "golden hour from the left"); style is one of standard, darker_but_realistic, clean, smooth, brighter, contrasted_n_hdr, just_composition. Spends credits like the same tool on the Astorie canvas (quote does not price it; tell the user it costs credits, per second for videos). Adds a new node linked from the source and returns its node_id with a job_id right away; get_job / jobs_wait return the result if it is still running. Call when the user named this edit or picked it in edit_options; when they already named it, do not show edit_options first.

relight_image

Removes a member from a workspace (owner or admin only): they lose access to its projects and shared credits, and their spending cap and invite links are dropped. Admins can remove members; only the owner can remove an admin; the owner cannot be removed. Confirm the exact person with the user before calling. Resolve member_user_id with get_workspace_usage first.

remove_workspace_member

Cuts the subject of an image of an Astorie project (or an image url) out onto a transparent background. Spends credits like the same tool on the Astorie canvas (quote does not price it; tell the user it costs credits, per second for videos). Adds a new node linked from the source and returns its node_id with a job_id right away; get_job / jobs_wait return the result if it is still running. Call when the user named this edit or picked it in edit_options; when they already named it, do not show edit_options first.

remove_background

Renames an existing project the user can edit (find it with list_projects). Only the name changes; the canvas is untouched.

rename_project

Shows the user's reusable Elements (characters, outfits, scenes, props) with a preview each, tabbed by kind, for the user to pick from. Their pick comes back as a message with element_id and file_id. For your own lookup use search_elements.

show_elements

Shows Astorie Director presets (world, look, movement, speed, lens, palette) and Astorie Ads templates with their cover images, tabbed by kind, for the user to pick from. Their pick comes back as a message with the kind and slug. Pass media "image" for an image (lca-image) request: only presets image mode takes are shown. For your own lookup (and saved palettes / products) use list_studio_options.

show_studio_options

Shows one past result in the Astorie result card (video player or image, with Open in Astorie): by job_id, or by the project_id and node_id of an image or video node. Call it when the user wants to see an earlier generation again. To check on a running job use get_job.

show_generation