Ava Studio for Agents

Permanently delete a brand profile, as Studio's Delete brand does (its campaigns and projects stay); ask the user first and pass confirm true, since it cannot be undone. If it was the primary brand another brand becomes primary; returns deleted_brand_id and primary_brand_id (null when no brand is left).

brand_delete

Clone one short-form video (TikTok, Instagram Reel or YouTube Short URL) into ONE on-brand brief that keeps its format, beats, pacing, hook mechanic and caption style. Sources up to 2 minutes. Costs 10 credits plus the AI usage, typically ≈ 25 credits in total; returns a job_id: poll jobs_get, then use draft_spec, draft_prompts or draft_open on the brief, saved in the brand's "From your agent" campaign in Ava Studio.

draft_clone

Draft briefs for a brand grounded in market videos and, when Meta is connected, its own best ads: short-form video by default, or with output a carousel or static image ad; concepts only, no media. Costs 10 credits per brief plus the AI usage, typically ≈ 25 credits per brief in total. Returns a job_id; poll jobs_get, then use draft_spec, draft_prompts, draft_check or draft_open on the brief ids, saved in the brand's "From your agent" campaign in Ava Studio.

draft_briefs

Draft 1-5 more concepts into the campaign's current plan run, reusing its research; call plan_run first if this period has no run yet. Costs 10 credits per concept drafted; it never produces media, so on a campaign whose mode is produce it fails with invalid_input. Returns a job_id; poll jobs_get, the result lists the new concepts.

concepts_draft_more

Apply one plain-language edit to a produced project's timeline: retime or trim scenes and b-roll, cut dead air, move captions onto their beat or off a face or the product, resize or move picture-in-picture and split-screen media. It cannot change words, add, remove or regenerate scenes, or touch music and voice. Costs 10 credits plus the AI usage; returns a job_id, poll jobs_get, then call export_render for the edited file.

project_edit

Quote 1-20 generations at Studio's media credits for the model and settings (what the API charges too), plus the total; video bills on the clip's measured length, which can run a frame long (4 s may bill as 4.04 s). Work priced after the fact is quoted at its most: image_layerize at 17 layers of a large image (up to 1536×1536 pixels costs half), video_remove_background at the duration given (else 60 s). Tell the user the total first; a key with a monthly limit needs room for it.

generation_estimate

Score a brief 0-100 against winning videos in its niche, with strengths, risks and the most similar winners; the score is an AI judgment, not a calibrated prediction of performance. Costs 3 credits plus the AI usage, typically ≈ 4 credits in total. Use it to compare briefs before committing; revise weak ones with draft_iterate.

draft_check

Export a brand profile as a portable brand.md (format md) or raw JSON (format json). Use it to save brand context into a repo or hand it to another tool.

brand_export

Render a Studio project to a downloadable MP4 or image file; watermark:auto (default) follows the owner's plan, watermark:required includes it, and watermark:none requires a paid owner. Costs 10 credits. Free when the project is unchanged since its last export with the same watermark setting; poll jobs_get for output_url.

export_render

Videos that recently broke out far above their creator's normal views, for a niche or brand category: the best starting references for draft_briefs.research_video_ids. Costs 1 credit per call. Every example comes with its TikTok link; always show those links to the user next to each insight.

research_breakouts

Find videos similar to a corpus video (video_id) or to free text, by hook or by visual style (requires video_id or text), to widen a set of references before draft_briefs. Costs 2 credits per call. Every example comes with its TikTok link; always show those links to the user next to each insight.

research_similar

List the voices Studio offers for voiceovers (name, gender, accent, description and a preview link); with query, also search ElevenLabs' community voices. Pass a voice_id to audio_generate.

voices_list

Generate a voiceover from a script in a voice from voices_list, music from a prompt, or a sound effect from a prompt (or matched to a video with mmaudio); it is saved to the user's Studio library, ready for timeline_add. Costs Studio's price for the model and settings (the same media credits as in Ava Studio): quote it with generation_estimate first. Returns a job_id; poll jobs_get for the audio.

audio_generate

Make one 5-second vertical B-roll clip from 1-4 of the brand's images (product photos, app screens or web pages, by media_id) with a Studio B-roll template; the clip joins the brand's media, analyzed. Costs the media credits Studio charges for it, about 75 (a key with a monthly limit needs room for them). Returns a job_id (a few minutes); poll jobs_get, the result is the new media_item and its project_id, and media_credits_charged what the media cost.

broll_create

Generate 1-4 images with any Studio image model from a prompt, optionally editing or steering with reference images; they are saved to the user's Studio library, and with save_to_brand_id to that brand's media. Costs Studio's price for the model and settings (the same media credits as in Ava Studio): quote it with generation_estimate first. Returns a job_id; poll jobs_get for the images' urls and library_asset_ids.

image_generate

Generate 1-4 variants of one scene of a project with any image or video model, into a scene from project_get or a new one after the last. Costs Studio's price for the model and settings (the same media credits as in Ava Studio), per variant: quote it with generation_estimate (count = variant_count). Returns a job_id; jobs_get gives the variants and, for a scene without media, where the first ready one went (placement); swap in another with scene_select_variant.

scene_generate

Add timed captions to a project from its voiceover, or from the audio element given, as Studio's auto captions do. Costs Studio's price for caption timing: 2 credits per started minute of audio, at least 2 (a 2-minute voiceover costs 4). Returns a job_id; poll jobs_get for the captions and media_credits_charged.

captions_generate

Generate one video with any Studio video model from a prompt, a start (and end) frame, reference images or videos, a motion reference, a video to extend or edit, or several shots; it is saved to the user's Studio library, and with save_to_brand_id to that brand's media. Costs Studio's price for the model and settings (the same media credits as in Ava Studio): quote it with generation_estimate first. Returns a job_id (minutes); poll jobs_get for the video.

video_generate

Get the Ava Studio link where the user connects the brand's Meta ad account (Meta sign-in happens in their browser, not through the API). Show the connect_url and instructions to the user, then call meta_status once they are done.

meta_connect

Get the Ava Studio link where the brief can be reviewed, approved and produced. Share it with the user when they want to see or approve a draft.

draft_open

Add 1-10 images or videos to a brand (https links, brand_media_upload_url's media_url or brand_get urls; 30 max) and analyze each so Ava can use it; non-H.264 video, such as an iPhone's HEVC, is converted to an H.264 MP4 copy. Costs 2 credits per item imported and analyzed: failed lists items not added, analyzed false with analysis_error marks items added but not analyzed (add again to retry), neither charged. Returns a job_id; jobs_get then has the items and media_readiness.

brand_media_add

Import 1-10 public https images, videos or audio files, or library_upload_url's media_url, into the user's Studio library. Links are copied into Ava's storage (images up to 10 MB, videos 50 MB, audio 9.2 MB) so the asset outlives its source, uploads stay where they are, and video that is not H.264, such as an iPhone's HEVC, is converted to an H.264 MP4 copy. Returns a job_id; poll jobs_get for each library_asset_id, and failed for links not imported.

library_add

List the account's brands (id, name, url, primary flag). Use it to pick a brand_id for research and drafting; call brand_get for full details.

brand_list

List a campaign's concepts (the creative ideas Ava drafted), newest first, optionally for one plan run or status: hook, status, output kind and creative_id once approved. A concept_id is also a brief id, so draft_get shows its full script; then approve with concept_approve or reject with concept_reject.

concept_list

List a campaign's creatives (approved and produced concepts), newest first, optionally for one plan run: status, output URLs and project ids. Call creative_get for one creative's post package, or creative_produce on approved concepts not produced yet.

creative_list

List the account's Ava Studio campaigns, newest first, optionally for one brand: name, type, automation and whether setup is complete. Use campaign_get for a campaign's settings and latest plan run, or campaign_create to start one.

campaign_list

List recent briefs, newest first, optionally for one brand or campaign. Use draft_get for full details.

draft_list

List the image, video and audio models Studio offers, optionally of one kind: modes, aspect ratios, durations, resolutions, qualities, reference limits and Studio's credit prices (the API charges the same). Pick a model here before image_generate, video_generate, audio_generate or scene_generate, then quote the cost with generation_estimate.

models_list

List the user's Studio media library, newest first, optionally by kind or origin (generated or uploaded): each asset's library_asset_id, url, kind and length. Pass {library_asset_id} to any media input, such as timeline_add's source or video_generate's start_image.

library_list

List Studio's video templates, optionally for one use case or matching words in the title: title, use case, aspect ratio and preview. Read one with template_get for its variables and price, then make a project with project_from_template.

template_list

List the account's Studio projects (editable videos and image sets), newest first, optionally for one campaign. Call project_get for a project's scenes and captions.

project_list

Run Studio's project planner to clone videos or TikTok photo carousels and plan with attached media; start with project_create. Set generate:true to produce, or relay needs_input questions and send the user's answer in the same project. Costs 10 credits plus AI tokens and Studio media; AI reservations grow within the balance/key budget without a fixed turn cap; media_credit_limit bounds estimated media spend (default 300); poll jobs_get.

project_ask

Produce one concept into finished media (video, carousel or static image) like Studio's Generate button, which picks an actor if none is set. Costs 50 credits plus the media credits Studio charges (about its credit_range; a key's monthly limit needs room for both); no fee when already produced or producing (started false) or production fails. Takes minutes: returns a job_id; poll jobs_get for the Creative, or a failed job whose error names the reason and the creative for creative_get.

creative_produce

Read a brand profile; pass sections to fetch only part of it (identity, audience, products, sources, visual, market). Use before drafting to check claims and audience (fix gaps with brand_update), and before producing to check the visual section's media_readiness: below good, videos get no B-roll and AI-generated product shots, so ask the user for real media (brand_media_upload_url, brand_media_add) or make clips with broll_create.

brand_get

Write per-shot generation prompts for a specific video or image model (seedance-2, veo-3.1, kling-3, sora-2, runway-gen4, nano-banana, gpt-image, generic). Carousel and static briefs get one image prompt per slide and need an image target (nano-banana, gpt-image or generic). Ava does not generate the video or images; run the prompts in your tool of choice.

draft_prompts

Turn a brief into a shot list: per-shot role, duration, action, framing, camera, performer, speech, on-screen text and audio. Use when producing the video yourself; follow with draft_prompts.

draft_spec

Read one campaign: brief, objective, type, automation settings, featured brand media and a summary of its latest plan run. Call plan_run to research and draft concepts, or concept_list to see the ones already drafted.

campaign_get

Read a campaign's plan run (the latest unless period_start is given): status, step labels, concept counts and ids, and Ava's research summary and strategy. Use it to follow a run started in Studio or by the schedule; when status is ready, call concept_list.

plan_get

The user's own Meta ad results (spend, CTR, hook rate, hold, cost, 0-100 score) with account medians and a short why_it_works / why_it_didnt per ad. Call meta_status first; if not connected, follow next_steps to meta_connect. Cite ads by name, and pass winning ad_ids to draft_briefs.my_ad_ids.

research_my_ads

Read one creative (an approved or produced concept): production status, output URLs, the post package (caption, hashtags, publish status) and its Studio project. To change it, edit the project with project_edit and get a new file with export_render.

creative_get