ViralMint

Free. Treats a finished plan as made and writes a NEW plan from it. Nothing is made or charged.

Args: plan: the finished short's plan. kind: like_this | part2 | new_look | translate | shorter. message: what to change (optional, e.g. the language for translate), max 4000 chars. history: the history from the last answer (optional, max 40 turns).

Returns: The same shape as ai_short_draft.

Costs the render price (quote.render_cents from ai_short_estimate): makes the project AND starts the render in one call. Pass that price as confirm_cents (the most you agree to; the actual charge is at most that). Pass an idempotency_key so a retry never buys twice.

Args: plan: the plan from ai_short_draft / ai_short_revise. confirm_cents: the price you showed the user, whole cents. idempotency_key: any unique string (1-200 printable chars). attachment_ids: the staged image ids the plan names (up to 8). origin: create (optional; marks it as started from the Create page).

Returns: {ok, project_id, job_id, kind: "render", poll_after_s: 15, cents}. Poll with wait_for_job, or studio_get_project. If the render is refused after the project was made, the answer carries project_id and a hint: call studio_render(project_id, confirm_cents), do NOT call ai_short_create again (that makes a second project).

Free. Plans a finished AI short (several AI video shots, voice or dialogue, music, captions) from an idea. Nothing is made or charged. Show the user the reply, the shots and quote.render_cents, refine with ai_short_revise, then make it with ai_short_create.

Args: brief: the idea in the user's words, 1-4000 chars, any language. length: target seconds (3-60; longer is planned as 60), only when the user named one. quality: fast (cheapest) | pro | ultra (best); the director picks when omitted (the desktop tool defaults to pro). aspect: 9:16 (default) | 16:9 | 1:1. source: a source from remix_read_source / read_article: makes an ORIGINAL short from it. angle: with source: similar (default) | my_niche | part2 | rewrite. attachment_ids: staged image ids (up to 8). persona_id: a saved persona whose photos are staged for you.

Returns: {ok, reply, plan|null, changed, chips:[{label, message?, action?}], notes, quote?:{render_cents, items, blockers, fits}, history}. A chip with action top_up or sign_in means the balance or sign-in needs the user. Pass history back to ai_short_revise.

Free. The price of making a plan, from the server quote. Pass quote.render_cents to ai_short_create as confirm_cents.

Args: plan: the plan from ai_short_draft / ai_short_revise.

Returns: {ok, quote:{render_cents, outstanding_cents, fits, blockers, warnings, items}, confirm_hint}

Free. Changes an AI short's plan in plain words ("make it funnier", "music only", "15 seconds"). A question gets an answer in reply and the plan back unchanged. Nothing is made or charged.

Args: plan: the plan from ai_short_draft / ai_short_revise. instruction: what to change, 1-4000 chars. history: the history from the last answer (optional, max 40 turns). attachment_ids: staged image ids (up to 8).

Returns: The same shape as ai_short_draft.

Free. Cancels your own running render, song analysis or My audio listening and refunds whatever it charged (a render that already landed parts keeps only those). Never charges. A cancelled job still counts toward this token's daily limit until midnight UTC. AI clips, music tracks and voiceovers can't be cancelled once started.

Args: job_id: r_ (render), a_ (song analysis) or au_ (My audio).

Returns: {ok, cancelled, best_effort, message}: best_effort true = it is stopping; poll get_job until it ends.

Free. Reads what the user wants to make and names the studio for it: call it first when the ask is vague.

Args: message: the user's words (any language), 1-4000 chars. hint: idea | script | song | photos | link | asset (optional; forces that engine).

Returns: {ok, engine: ai_short|script|music|asset|ask, question?, asset_kind?, song_brief?, prompt, next_tool}

Free. What this web server cannot do: features only the desktop app has (with the download link), and browser tool pages at viralmint.net/app it cannot drive. Call it before telling the user something is impossible.

Returns: {ok, message, download_url, features:[{name, why}], web_page_only:[{name, url}]}

Free (same hourly allowance as the portal). Rewrites an image or video prompt into a stronger one; keeps quoted text, colours, counts and structured shot lists exactly, and returns those unchanged.

Args: kind: image | video. prompt: the draft, max 4000 chars (empty writes a starting one). context: one line of context (optional, max 500 chars).

Returns: {ok, prompt, unchanged?: true}

Costs the model's per-image price, charged only after confirm_cents matches the quote: makes one image and saves it to your Library.

Args: prompt: 1-4000 chars. aspect: e.g. 9:16 (default), 16:9, 1:1, 4:5, 3:4. model: an image model id from list_models (optional). reference_library_ids: up to 3 image ids from library_list (kind image). confirm_cents: the price the user agreed to (from tool_cost_estimate); 0 with quote_only. idempotency_key: unique per purchase; a retry with the same key never buys twice. Idempotency is keyed on (this token, this tool, idempotency_key), not on the arguments: reusing an idempotency_key with different arguments returns the first result. quote_only: true returns the price and buys nothing.

Returns: {ok, kind:'image', library_id, model, cents} (use library_get for the file)

Costs a flat price per track, charged only after confirm_cents matches the quote: starts one AI music track.

Args: prompt: 1-3000 chars (genre, mood, instruments). duration_s: 5-240 seconds. confirm_cents: the price the user agreed to (from tool_cost_estimate); 0 with quote_only. idempotency_key: unique per purchase; a retry with the same key never buys twice. Idempotency is keyed on (this token, this tool, idempotency_key), not on the arguments: reusing an idempotency_key with different arguments returns the first result. quote_only: true returns the price and buys nothing.

Returns: {ok, job_id, kind:'music', poll_after_s, cents}: poll with wait_for_job; the track lands in your Library A job that fails is refunded to the balance, but it still counts toward this token's daily limit until midnight UTC.

Costs the image model's price, charged only after confirm_cents matches the quote: makes one thumbnail-shaped image and saves it to your Library.

Args: prompt: 1-4000 chars. aspect: 16:9 (YouTube) or 9:16. model: an image model id from list_models (optional). reference_library_ids: up to 3 image ids from library_list (kind image). confirm_cents: the price the user agreed to (from tool_cost_estimate); 0 with quote_only. idempotency_key: unique per purchase; a retry with the same key never buys twice. Idempotency is keyed on (this token, this tool, idempotency_key), not on the arguments: reusing an idempotency_key with different arguments returns the first result. quote_only: true returns the price and buys nothing.

Returns: {ok, kind:'image', library_id, model, cents}

Costs the model's per-second price for the chosen resolution and audio, charged only after confirm_cents matches the quote: starts one AI video clip.

Args: prompt: 1-4000 chars. model: a video model id from list_models. seconds: 1-60. Snapped to the nearest length the model allows (the durations listed by list_models; a tie takes the shorter); the answer says the real length. resolution: e.g. 720p (required: it changes the price). generate_audio: true or false (required: it changes the price). aspect: e.g. 9:16. first_frame_library_id: an image id to start the clip from (optional). reference_library_ids: up to 4 image ids (optional; each can add to the price). confirm_cents: the price the user agreed to (from tool_cost_estimate); 0 with quote_only. idempotency_key: unique per purchase; a retry with the same key never buys twice. Idempotency is keyed on (this token, this tool, idempotency_key), not on the arguments: reusing an idempotency_key with different arguments returns the first result. quote_only: true returns the price and buys nothing.

Returns: {ok, job_id, kind:'video', poll_after_s, model, duration, resolution, cents}: poll with wait_for_job; the finished clip lands in your Library A job that fails is refunded to the balance, but it still counts toward this token's daily limit until midnight UTC.

Costs per 1,000 characters of the text (at least 1 cent), charged only after confirm_cents matches the quote: starts one narration of the text.

Args: text: 1-100000 chars. voice: a voice name from list_voices. model: a tts model id from list_models (optional; Premium voices need their own model and English text). confirm_cents: the price the user agreed to (from tool_cost_estimate); 0 with quote_only. idempotency_key: unique per purchase; a retry with the same key never buys twice. Idempotency is keyed on (this token, this tool, idempotency_key), not on the arguments: reusing an idempotency_key with different arguments returns the first result. quote_only: true returns the price and buys nothing.

Returns: {ok, job_id, kind:'tts', poll_after_s, cents}: poll with wait_for_job (the finished job has audio_url) A job that fails is refunded to the balance, but it still counts toward this token's daily limit until midnight UTC.

Free. The status of a long-running job (a render, an AI clip, a music track, a long voiceover). Studio-internal jobs (p_ plan, voice and visual jobs) answer studio_internal_job here: their result lands in the project, read it with studio_get_project.

Args: job_id: r_/a_/au_ (render, analysis), v_ (AI clip), m_ (music) or t_ (voiceover).

Returns: {ok, kind, job_id, status, percent?, step?, video_url?, error?}

Free (60 an hour). Writes an AI Image / AI Thumbnail prompt with the user and returns a card plus the arguments for generate_image / generate_thumbnail. Nothing is made or charged. Pass history and card back each turn.

Args: message: the user's words, 1-4000 chars. mode: image (default) | thumbnail. history: the history from the last answer (optional, max 40 turns). card: the last card, to change it (optional). aspect: 9:16 | 16:9 | 1:1 | 4:5 | 3:4 (thumbnail: 16:9 | 9:16). has_refs: true when you will pass reference_library_ids to the generate tool.

Returns: {ok, reply, card:{mode, prompt, negative, look, aspect, count, title, use_refs}|null, generate_args?:{prompt, aspect}, chips:[{label, message?, action?}], history}

Free. Delete one item and its file from the WEB Library. Cannot be undone.

Args: library_id: from library_list.

Returns: {ok}

Free. One item in the WEB Library with a signed download URL (valid about an hour).

Args: library_id: from library_list.

Returns: {ok, generation, download_url, attachment_url}

Free. Your generations in the WEB Library at viralmint.net (videos, images, voice, music), newest first — not files on this computer (that is the desktop app's server). Rows expire: video and other rows live 7 days, files 12.

Args: kind: video | image | voice | music (optional). limit: 1-50 (default 20).

Returns: {ok, generations:[{generationId, kind, prompt, createdAt, shareSlug?, ...}]}

Free. Make a public share link for one WEB Library item (anyone with the link can view it until you unshare it or it expires).

Args: library_id: from library_list.

Returns: {ok, slug, share_url, kind}

Free. Turn off the public share link of one WEB Library item.

Args: library_id: from library_list.

Returns: {ok}

Free. The models ViralMint offers for one kind of output, with their prices. Use the ids in generation tools.

Args: kind: chat | image | video | tts | music.

Video models that cannot be bought here are left out.

Returns: {ok, models:[{id, name, tier?, price_cents_per_second?, price_cents_per_image?, max_duration_s?, durations? (video: the exact clip lengths the model accepts), resolutions?}]}

Free. The voices generate_voiceover can speak: standard Gemini voices (about $0.12 per 1K characters, any language) and Premium MiniMax voices (about $0.20 per 1K characters, English only). Quote a voiceover with tool_cost_estimate for the exact price.

Args: provider: standard | premium (optional; default both).

Returns: {ok, standard_voices:[{voice, model}], premium_voices:[{voice, model, premium:true, english_only:true}]}

Free. Makes a Studio project from the plan; nothing is rendered. Then price it (the quote is in the answer) and call studio_render(project_id, confirm_cents). Captions on a song are always whole lines (never word sync).

Args: song_id: a read song. music_plan: the plan to make. origin: create (optional).

Returns: {ok, project:{id, status, scenes, quote:{render_cents,...}}}: never call it twice for one plan.

Free for the first songs each day; then 3¢ a song. Pass confirm_cents: 3 to allow the charge; with 0 it answers price_changed and charges nothing. Plans the video for a read song in plain words ("neon city at night"); nothing is rendered. It waits up to 20 s for the plan; if it is not ready the answer says poll_again: call music_video_turn(turn_id). Captions on a song are always whole lines (never word sync). Idempotency is keyed on (this token, this tool, idempotency_key).

Args: song_id: a song already read with song_analyze. message: what the user wants, 1-4000 chars, any language. history: the history from the last answer (optional, max 40 turns). music_plan: the last music_plan, to revise it. confirm_cents: the most the user agreed to pay, in cents (3 allows the paid-song charge). idempotency_key: unique per turn (recommended).

Returns: {ok, turn_id, status: done|running, reply, music_plan, chips:[label], dropped, history, cents} or {poll_again, next_tool}. Next: music_video_estimate, then music_video_create.

Free. The server quote for a plan and the plan as the server made it. Pass quote.render_cents to studio_render as confirm_cents. Captions on a song are always whole lines (never word sync).

Args: song_id: a read song. music_plan: the music_plan from music_video_director.

Returns: {ok, quote:{render_cents, outstanding_cents, fits, blockers, warnings, items}, music_plan}

Free. The answer of a music_video_director turn that was still running. Waits up to 20 s. It returns no history: append your message and this reply to history yourself before the next director call. Captions on a song are always whole lines (never word sync).

Args: turn_id: from music_video_director.

Returns: {ok, turn_id, status: done|running, reply, music_plan, chips:[label], dropped} or {poll_again, next_tool}.

Free. Saves 1-5 staged photos of one person as a Persona (at most 5 Personas). consent: true only when the user has told you this is them, or that they have the person's permission.

Args: name: 1-120 chars. photo_attachment_ids: 1-5 attachment ids from upload_finish or stage_library_item. consent: must be true. notes: optional.

Returns: {ok, persona:{id, name, photo_count, ...}}. Errors: photo_missing, too_many.

Free. Deletes a Persona and its saved photos. Cannot be undone.

Args: persona_id: from persona_list.

Returns: {ok}

Free. Your saved Personas (reference photos of one person, up to 5).

Returns: {ok, personas:[{id, name, notes, photo_count, photo_urls, consent_at}]}

Free. Copies a Persona's photos into fresh staged attachments so a director or project can use them as references.

Args: persona_id: from persona_list.

Returns: {ok, attachments:[{id, url, width, height}]}

Free. Your prepaid balance, today's spend and your daily cap, in US cents.

Returns: {ok, balance_cents (can be fractional, e.g. 512.5), balance_usd (string, e.g. "$5.12": the balance FLOORED to a whole cent, never rounded up, so it is what you can safely say you can spend), daily_spent_cents, daily_cap_cents}

Free (30 pages an hour). Reads a web page into a short brief for the script coach. Text pages only on the web: a video link answers desktop_only.

Args: url: an https link to an article or post (max 2000 chars).

Returns: {ok, source:{url, title, brief:{about, facts[], audience, tone}, excerpt, chars, cached}}: pass source to script_coach or ai_short_draft. A video link: {ok:false, error_code:'desktop_only', download_url}.

Free (30 pages an hour). Reads a source page into a brief the AI Video director builds an original short from. Text pages only on the web: a video link answers desktop_only.

Args: url: an https link to an article or post (max 2000 chars).

Returns: {ok, source:{url, title, brief:{about, facts[], audience, tone}, excerpt, chars, cached}}: pass source to script_coach or ai_short_draft. A video link: {ok:false, error_code:'desktop_only', download_url}.

Free (60 an hour). Writes or improves a Video Studio script with the user, one turn at a time. The web server keeps nothing: pass history back each turn.

Args: message: the user's words, 1-4000 chars. history: the history from the last answer (optional, max 40 turns). script: the current script, to edit it (optional, max 10,000 chars). source: a source from read_article (optional). length: target seconds, 15-240, only when the user named one. aspect: 9:16 | 16:9 | 1:1.

Returns: {ok, mode: write_script|answer, reply, script, target_seconds?, chips:[{label, message?, action?}], history}. Then studio_create_project with the script.

Free for the first songs each day; then 3¢ a song. Pass confirm_cents: 3 to allow the charge; with 0 it answers price_changed and charges nothing. Listens to the song for its beats, sections and lyrics (a few minutes of work in the background). A repeat of the same song is free. A failed or cancelled read is refunded, but still counts toward this token's daily limit until midnight UTC. Captions on a song are always whole lines (never word sync). Idempotency is keyed on (this token, this tool, idempotency_key).

Args: song_id: from song_from_library. lyrics: optional pasted lyrics (max 20,000 chars) to align instead of listening for words. confirm_cents: the most the user agreed to pay, in cents (3 allows the paid-song charge). idempotency_key: unique per call (recommended).

Returns: {ok, job_id, status, poll_after_s: 5, cents}: poll with wait_for_job (a_), then song_get. A song already read answers {analysis_ready: true, next_tool: 'song_get'} with no job to poll. Errors: price_changed {price_cents}, rate_limited, outcome_unknown.

Free. Makes a Music Video song from an audio file in your web Library (a video isn't accepted). rights_confirmed: true only when the user has told you they own this song or have permission to use it. It does not read the song: call song_analyze next. Captions on a song are always whole lines (never word sync).

Args: library_id: an audio item from library_list. rights_confirmed: must be true (see above).

Returns: {ok, song_id, size}

Free; never starts an analysis. The song and, once read, a summary of its analysis (never the raw words, beats or energy). Captions on a song are always whole lines (never word sync).

Args: song_id: from song_from_library.

Returns: {ok, song_id, analyzed, audio_url, analysis?:{duration, bpm, language, sections:[{id,label,s,e}], lines:[{text,s,e}], line_count, word_count, beat_count}}

Free. Copies an image or video from your WEB Library into staging so a Persona, an AI short or a project can use it; the Library original is never touched. rights_confirmed: true only when the user has told you they have the rights to it, including anyone shown.

Args: library_id: an image or video item from library_list. rights_confirmed: must be true.

Returns: {ok, attachment_id, url, width?, height?, media?, duration?}

Free. Suggestions for ONE scene's line; nothing is changed. Apply a pick with studio_patch (set_line).

Args: project_id: project. scene_uid: the scene. action: punchier | shorter | clearer | hook | custom. instruction: required for custom, up to 300 characters.

Returns: {ok, suggestions:[...]} as the editor shows them.

Free. Put one candidate from studio_stock_candidates on a scene.

Args: project_id: project. scene_uid: the scene. candidate: the candidate object exactly as returned. if_revision: the revision you read.

Returns: {ok, project:{...summary}} or {ok:false, error_code:"revision_conflict", revision}

Costs 2 cents: listens to a voice recording from your Library and makes a Studio project from it (scenes timed to your voice). confirm_cents is the most you agree to pay: the step charges what it costs, never more, and refuses with price_changed (charging nothing) when it costs more. Call it with confirm_cents: 0 to learn the price of a paid step (the answer is price_changed with price_cents; nothing is charged). A free step (a standard voice, a visual already bought) just runs. Idempotency is keyed on (this token, this tool, idempotency_key), not on the arguments.

Args: library_id: a voice/audio item from library_list. confirm_cents: the most the user agreed to pay, in cents. idempotency_key: unique per purchase (recommended).

Returns: {ok, project_id, job_id, kind:'render', poll_after_s, cents}: the job (au_) is the listening step; poll with wait_for_job, then studio_get_project and studio_render the result. Cancel with cancel_job.

Free. Start a Video Studio project from a script (nothing is planned, voiced or rendered). Next: studio_plan, then studio_get_project.

Args: script: the narration, up to 10,000 characters. title: optional. aspect: 9:16 (default) | 16:9 | 1:1. visual_style: a look id from studio_enums. settings: optional partial settings (voice, captions, music) as in studio_enums. origin: "create" when started from the Create page.

Returns: {ok, project:{id, title, status, revision, scenes, settings, quote:{render_cents,...}, notice?}}

Free. Permanently delete a project (refused while it renders or plans). Rendered videos in the Library stay.

Args: project_id: project.

Returns: {ok}

Free. Change a project in plain words ("shorter hook", "bold captions"); edits the SAME project, nothing renders or bills. Same as the desktop tool; project_id may be "latest" (the newest project).

Args: instruction: what to change, up to 500 characters. project_id: a project id, or "latest" (default).

Returns: {ok, applied:[sentences], summary, project, outstanding_cents, render_cents}. Empty applied means nothing changed; summary says why.

Free. The Studio's option lists: voices and voice providers, caption_styles ({value,label}, from the cloud published list), visual styles/looks, aspects, AI tiers. Read before setting any of them.

Returns: {ok, caption_styles:[{value,label}], ...lists}

Free. The server's render price for the project as it is now. Pass render_cents to studio_render as confirm_cents.

Args: project_id: project.

Returns: {ok, project_id, revision, status, quote:{render_cents, fits, blockers, items}}

Free. One project: scenes (line, timing, visual), settings, the server's price quote and the revision you need for edits.

Args: project_id: from studio_list_projects. detail: summary (default) | full (the editor's whole envelope, large).

Returns: {ok, project:{id, title, status, revision, aspect_ratio, total_seconds, render_job_id, last_render_job_id, render_alive, voice_job_id (null when no voice job runs), plan_job_id (null when no plan runs), music_generating, plan_warnings?, input, settings, scenes:[{uid, line, duration?, visual:{kind, prompt, seconds, state?}}], quote, balance_cents}}

Free. Import your Library videos or images into the project's media bin (then bind them with studio_patch).

Args: project_id: project. library_ids: 1-10 Library item ids (library_list).

Returns: {ok, ...the imported media as the editor reports it}

Free. Your Video Studio / AI short / Music Video projects on the web, newest first.

Args: limit: 1-50 (default 24).

Returns: {ok, items:[{id, title, status, aspect_ratio, scenes, duration_seconds, updated_at, ...}]}

Costs the price of one AI music track for the project (a track already bought for this genre and length re-selects free). confirm_cents is the most you agree to pay: the step charges what it costs, never more, and refuses with price_changed (charging nothing) when it costs more. Call it with confirm_cents: 0 to learn the price of a paid step (the answer is price_changed with price_cents; nothing is charged). A free step (a standard voice, a visual already bought) just runs. Idempotency is keyed on (this token, this tool, idempotency_key), not on the arguments.

Args: project_id: project. genre: 1-40 chars, e.g. "lofi". confirm_cents: the most the user agreed to pay, in cents. idempotency_key: unique per purchase (recommended).

Returns: {ok, job_id|null, reused?, cents, poll}: poll studio_get_project until project.music_generating is false.

Free. Apply editor ops (set_line, split, merge, set_setting, bind_visual, ...) in one step. A 409 means the project changed: you get the new revision and the ops are NOT re-applied.

Args: project_id: project. ops: 1-50 ops, each {op, ...fields}. if_revision: the revision you read.

Returns: {ok, project:{...summary}} or {ok:false, error_code:"revision_conflict", revision}

Free. Plan the project: split scenes and choose footage (30 plans a day). Runs in the background; poll studio_get_project until project.plan_job_id is empty. Takes no price.

Args: project_id: from studio_create_project. scene_uids: optional, up to 40 scene ids to re-plan only those.

Returns: {ok, job_id, poll}

Costs the project's render price (quote.render_cents from studio_estimate_project): renders the saved project exactly as it is. confirm_cents is the most you agree to pay: the step charges what it costs, never more, and refuses with price_changed (charging nothing) when it costs more. Call it with confirm_cents: 0 to learn the price of a paid step (the answer is price_changed with price_cents; nothing is charged). A free step (a standard voice, a visual already bought) just runs. Idempotency is keyed on (this token, this tool, idempotency_key), not on the arguments.

Args: project_id: from studio_list_projects (or ai_short_create when it asks you to finish). confirm_cents: the most the user agreed to pay, in cents. idempotency_key: unique per purchase (recommended).

Returns: {ok, job_id, kind:'render', poll_after_s, cents}: poll with wait_for_job (r_). Cancel with cancel_job (refunds). Errors: price_changed {price_cents}, blocked {blockers}, already_rendering, outcome_unknown (check studio_get_project before retrying).

Free. Search stock clips for a project (aspect-aware). Pass one candidate, untouched, to studio_bind_stock.

Args: project_id: project. q: query, at least 2 letters.

Returns: {ok, candidates:[up to 12 candidate objects]}

Costs the price of one AI image or AI clip for a scene (an identical one this project already bought re-binds free). confirm_cents is the most you agree to pay: the step charges what it costs, never more, and refuses with price_changed (charging nothing) when it costs more. Call it with confirm_cents: 0 to learn the price of a paid step (the answer is price_changed with price_cents; nothing is charged). A free step (a standard voice, a visual already bought) just runs. Idempotency is keyed on (this token, this tool, idempotency_key), not on the arguments.

Args: project_id: project. scene_uid: the scene. kind: ai_image | ai_clip. prompt: what to show, 1-600 chars. model: optional model id from studio_enums / list_models. confirm_cents: the most the user agreed to pay, in cents. idempotency_key: unique per purchase (recommended).

Returns: {ok, job_id|null, reused?, cents, poll}: poll studio_get_project until that scene's visual.state is no longer "generating"; the result lands on the scene.

Costs the voice price for the scenes that need a take (a standard voice is free; a Gemini or Premium voice is not). confirm_cents is the most you agree to pay: the step charges what it costs, never more, and refuses with price_changed (charging nothing) when it costs more. Call it with confirm_cents: 0 to learn the price of a paid step (the answer is price_changed with price_cents; nothing is charged). A free step (a standard voice, a visual already bought) just runs. Idempotency is keyed on (this token, this tool, idempotency_key), not on the arguments.

Args: project_id: project. confirm_cents: the most the user agreed to pay, in cents. scene_uids: optional, up to 40 scene ids; omit for every scene without a take. idempotency_key: unique per purchase (recommended).

Returns: {ok, job_id|null, cents, poll}: job_id null = nothing needed recording. Runs in the background: poll studio_get_project until project.voice_job_id is null.

Free. Your saved style presets ("My styles": look, voice, captions, aspect, music genre, length), at most 5. Read this before styles_put.

Returns: {ok, presets:[{id, name, look, voice, captions, aspect, music_genre, length_s, watermark_key}], updated_at}

Free. REPLACES the whole list of style presets, so send the complete list you want (from styles_get, changed): a partial list deletes the rest. At most 5, unique ids. A Premium voice is removed on save. It reads the saved list first and refuses if that read fails, and when a list is already saved it needs expected_updated_at (the updated_at from styles_get) so it never overwrites a newer change.

Args: presets: the full list, max 5, each {id, name, look:{preset, prompt}, voice, captions, aspect, music_genre, length_s, watermark_key}. expected_updated_at: updated_at from styles_get.

Returns: {ok, updated_at}. Errors: conflict (changed since you read it: styles_get again), conflict_unchecked.

Free. The exact price of a paid tool for given arguments, asked from the same door that will charge. Pass the result as confirm_cents. Studio steps (studio_render, ai_short_create) answer the server quote; the other gate steps (studio_voice, studio_visual, studio_music, studio_create_from_audio) answer cost_cents null: call them with confirm_cents: 0 to learn the price. song_analyze / music_video_director: free or 3¢.

Args: tool: generate_image | generate_thumbnail | generate_video_clip | generate_music | generate_voiceover | transcribe_audio | studio_render (arguments.project_id) | ai_short_create (arguments.plan) | any other tool (a free tool answers 0). arguments: that tool's arguments, without confirm_cents / idempotency_key / quote_only.

Returns: {ok, tool, cost_cents, price_cents, confirm_cents, notes?}

Costs a flat price per recording, charged only after confirm_cents matches the quote: turns a voice or music item from your Library into text. Limits: 2 MiB of audio and 3 minutes.

Args: library_id: a voice or music id from library_list. language: a language code (optional). timestamps: true to include timestamps (optional). confirm_cents: the price the user agreed to (from tool_cost_estimate); 0 with quote_only. idempotency_key: unique per purchase; a retry with the same key never buys twice. Idempotency is keyed on (this token, this tool, idempotency_key), not on the arguments: reusing an idempotency_key with different arguments returns the first result. quote_only: true returns the price and buys nothing.

Returns: {ok, kind:'transcript', text, cents}

Free. Call after you sent the file to the URL from upload_start. The server checks the real file (type, size, bytes); a file that is not what it says is deleted. A song id goes to song_analyze; an attachment id to ai_short_draft / persona_create; a video is a Library item.

Args: upload_id: from upload_start. title: optional name for a video or project_media upload.

Returns: {ok, kind, ...}: attachment {attachment_id, url, width, height}; song {song_id, size}; video {library_id, generation}; project_media {asset_id, project_id}.

Free. Gets a one-time signed upload URL; YOU send the file with your own HTTP client (the server never sees the bytes), then call upload_finish. The URL lives for a few minutes (attachment/project_media about 10, song about 15, video about 5). Voice uploads are not available here.

Args: kind: attachment (an image up to 10 MB, staged for AI Video / Personas; JPEG, PNG, WebP) | song (audio up to 100 MB for Music Video; MP3, WAV, M4A, AAC, FLAC, OGG) | video (your own MP4/MOV up to 500 MB, saved to the Library; 20 a day) | project_media (an image up to 10 MB added to one Studio project; needs project_id). content_type: the file's MIME type, e.g. image/png, audio/mpeg, video/mp4. size_bytes: the exact size of the file. rights_confirmed: must be true for attachment, song and project_media, and only when the user has told you they own it or have permission, including anyone shown in an image. Not needed for video. project_id: for project_media only. filename: optional, ignored by the server.

Returns: {ok, upload_id, method: PUT|POST, url, headers? (PUT: send exactly these) | fields? (POST: multipart form fields, then the file last), curl (use as the path), expires_in_s, then: 'upload_finish(upload_id)'}

Free. What you spent, per action, newest first (each entry has costCents and a refund flag).

Args: limit: 1-200 rows (default 50). cursor: the previous answer's nextCursor, for the next page. since: ISO-8601 date; only rows at or after it.

Returns: {ok, entries:[{ts, action, category, costCents (cents; refunds are negative), refund (true for a refund)}], byCategory, totalCents, nextCursor}

Free. Wait up to max_wait_s (at most 20) for a job to finish. If it is still running you get poll_again: true — call again.

Args: job_id: as for get_job. max_wait_s: 1-20 (default 20).

Returns: the get_job answer, plus poll_again: true while it runs