What the API can do
Anything you do in the studio by hand, an agent can do with a key. Create one in the studio: «⋮» → API → Create key. The key’s rights cut the list itself: a read-only key never even sees the writing tools.
The list below is printed from the studio registry — it cannot fall behind it.
claude mcp add --transport http vini https://vinistudio.app/mcp \ --header "Authorization: Bearer $VINI_API_KEY"
| Tool | What it does | Price |
|---|---|---|
| reads | ||
| describe_studio | The studio catalogue: which nodes exist, what each one is for, their inputs, outputs and parameters. | — |
| model_advice | How the models actually differ, when to pick which, and what we verified ourselves. | — |
| list_skills | Studio and user techniques: what each one does, which nodes it fits and which model it was written for. | — |
| read_project_graph | What is on the project canvas right now: nodes (card title, parameters, result status) and the wires between them. | — |
| read_run_history | Run history of the project: which nodes ran, when, with what outcome and at what price. | — |
| trace | The causal chain behind a result: why this node or this material came out the way it did. | — |
| describe_scene | Contents of a scene container: what is inside it, what carries it and who changed it along the way. | — |
| list_my_elements | The user's element library (characters, objects, locations) — id, name, role, start of the description. | — |
| describe_element | The full description of ONE library element by id, when the list shows it truncated. | — |
| list_my_prompts | The user's saved prompts (id + title). | — |
| list_my_designs | The user's design systems (id + title). | — |
| list_generators | Ready-made setups for a node — model, format and prompt in one piece: the studio built-ins and this account’s own, marked mine (a recipe drops the author’s solutions there). | — |
| billing_status | How much money is on the account right now, and whether it is being metered at all. | — |
| billing_history | Where the money went: total for a period, broken down by kind of work, model, project and day. | — |
| list_projects | Projects on this account: name, when they were last edited, and the address that opens them. | — |
| list_artifacts | Account materials: images, clips, audio and uploaded documents. | — |
| get_artifact | One material and a link to download it. | — |
| list_jobs | Generation jobs: what is running right now and how the recent ones ended. | — |
| get_job | The state of a single job by its job_id. | — |
| lore_standard | The standard of a workspace's shared lore and what is not filled in yet. | — |
| list_workspaces | Workspaces on this account: id, name and how many projects each holds. | — |
| get_workspace_lore | A workspace's shared lore: documents the studio puts into the request of the text nodes of its projects. | — |
| get_run | The state of a node run by run_id: status, the nodes of the run and the amount spent. | — |
| price_quote | What a run will cost — before it happens. | — |
| list_social_accounts | Connected social accounts of the key owner: id, platform, nickname and state. | — |
| get_copilot_task | Follow a Vini task: status, question, event feed, spend and report. | — |
| builds | ||
| create_project | Create a new empty studio project and get its address. | — |
| apply_graph_ops | Build or change the project graph: add nodes, set their fields, connect them with wires. | — |
| expand_scenes | Expand the written scenes of a Prompt Scriptwriter into nodes, like the Expand all button in the studio. | — |
| set_project_format | Set or clear the video format for the whole project. | — |
| create_workspace | Create a new empty workspace and get its id. | — |
| move_project | Move a project to another workspace on this account. | — |
| put_workspace_lore | Write a shared lore document of a workspace: without doc_id a new one, with doc_id replace the text and title of an existing one. | — |
| write_lore | Write a workspace's shared lore by the lore wizard standard from the person's answers step by step. | — |
| upload_artifact | Upload a file to your materials: an image, video, audio, PDF, TXT or another document. | — |
| start_upload | Start uploading a large file to your materials. | — |
| upload_chunk | Send the next chunk of a file upload. | — |
| finish_upload | Finish a file upload and receive the material in your library. | — |
| cancel_upload | Cancel an unfinished file upload and remove its temporary chunks. | — |
| assemble_video | Stitch clips into one video. | — |
| edit_video | Trim a video at the ends. | — |
| extract_audio | Take the audio track out of a video. | — |
| import_clip | Fetch a video by link so you can work with it. | — |
| inspect_import | Find the available YouTube video qualities before importing. | — |
| put_publish_draft | Prepare a video or image post (an image goes to Instagram only): caption, cover frame and account — a person publishes it. | — |
| save_element | Save an Element — a character, object or place — to your studio library or update a saved one. | — |
| generates | ||
| run_node | Run a project node like the ▶ button in the studio: it and everything above it that is not fresh yet. | metered |
| stop_run | Stop a running node run by run_id: no new requests start, those already sent to the model finish and are paid. | metered |
| generate_text | Write text with a model — a short piece to a brief. | metered |
| generate_image | Draw a frame from a description and references. | metered |
| generate_music | Compose a music bed from a description of the mood (model and vocals are optional). | metered |
| generate_voice | Read text aloud in the chosen voice. | metered |
| clone_voice | Make a voice from a recording, to narrate with it later. | metered |
| isolate_audio | Isolate speech from audio/video (voice_url); bg_url is an optional, best-effort music/SFX/ambience residual, not a guaranteed clean stem. | metered |
| analyze_audio | Break down a sound — a track, song, speech or a video soundtrack — by answering your question. | metered |
| dub_video | Re-voice a finished clip in another language. | metered |
| upscale_image | Enlarge a frame without losing sharpness. | metered |
| write_script | Break an idea into scenes: what happens, what is in frame, who speaks. | metered |
| write_scene_prompts | Write scene prompts using the selected video model’s skill automatically. Supply its ID in params.video_model. For a saved graph node, prefer run_node: it reads the node’s video model itself. | metered |
| rewrite_scene | Rewrite one scene without touching the others. | metered |
| direct_scene | Break a scene down as a director would: camera movement, action, rhythm. | metered |
| make_subtitles | Make subtitles for a clip from its audio. | metered |
| normalize_subtitles | Tidy subtitles: line breaks, timings, punctuation. | metered |
| decorate_video | Dress a clip up — captions, plates, accents over the picture. | metered |
| generate_video | Shoot a clip. | metered |
| lipsync_video | Match speech to the character's lips in a finished clip. | metered |
| analyze_video | Break down someone else's reference clip in the language of a director and a cinematographer — breakdown, frame style, motion style and shots. | metered |
| start_copilot_task | Hand a task to Vini, the studio copilot: it builds the graph, runs nodes and returns a report within a spending ceiling. | metered |
| answer_copilot_task | Answer Vini's question on a task, optionally raising the spending ceiling. | metered |
| stop_copilot_task | Stop a Vini task: no new rounds start and the work done stays in the report. | metered |
Project links
create_project, list_projects and read_project_graph return url — the project’s address in the browser. Pass that url (or just its 12-character tail, or the id) as project_id to any tool; the studio resolves it to a project of your account. The link opens in the browser only for a person signed in to the key owner’s account (holding the link grants no access), and it survives moving and renaming the project. A foreign or missing project is refused exactly like a wrong id; the exception is list_jobs and list_artifacts: for a foreign or missing project, or a typo in the link, they return an empty list, and empty does not mean “nothing is running”. A link cannot be verified by a request: the site answers with the app shell for any well-formed address, whether the project exists or not; verify it with a tool (read_project_graph). Pass project_aspect to create_project: 9:16 for Reels/Shorts/TikTok, 16:9 for horizontal video, 1:1 for square posts, or 3:4 when the brief calls for it. An explicit user choice takes priority; ask if the intended output is unclear. Later use set_project_format with the current based_on_revision; project_aspect: null clears the default. Node and Scriptwriter overrides take priority. A change can make results stale, but generates nothing; an active run returns busy.
Upload files
Upload images, videos, audio, PDFs, TXT files and other documents with upload_artifact: send the original name as filename and the bytes as data_url (data:<MIME>;base64,…). A project is optional. The key needs permission to build.
For large files, use start_upload → upload_chunk → finish_upload. Start with the MIME type and original size in bytes; send chunks in order from index 0, using chunk_bytes from the response (4 MiB). Whole files allow up to 24 MiB; chunked files up to 2048 MiB. Use chunks near the 32 MiB JSON request limit. Use cancel_upload to cancel an unfinished upload.
The response includes artifact_id, the URL and file details. Attach media to a node with pin_file. Documents are preserved in full without automatic text extraction; use get_artifact to download them.
REST accepts the same JSON and Bearer key: POST to /api/artifacts/upload, or use /api/artifacts/upload/start, /chunk, /finish, /cancel for chunks. These five routes accept a key with permission to build. Example TXT upload:
curl 'https://vinistudio.app/api/artifacts/upload' \
-H "Authorization: Bearer $VINI_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"filename":"brief.txt","data_url":"data:text/plain;base64,SGVsbG8="}'
Machine-readable version for your agent — /mcp/llms.txt, no authentication required.
Not there yet: running a whole project with one call, and managing keys with a key — keys are created in the browser only.