analyze_ugc_reference
ChatGPTRead an uploaded workspace video/audio into shape and beats for plan_ugc.reference. Planning inspiration, not My Footage recreation. No customer credits. May take time; do not start paid generation before the analysis is returned.
approve_video_plan
ChatGPTTwo steps, always. 1) Without quote_id: returns the price of what the plan will make (credits_max is the most it can cost; only what is used is charged), what it makes, and a quote_id. Nothing is charged. Show the user the price and wait for their explicit yes. 2) Only after the user agrees: call again with that quote_id to start the build, then poll get_video_plan. Never pass a quote_id the user has not approved. Approving also agrees to send the brief and approved media to WyvStudio's AI providers. When status is look_ready and the user likes the images, pass look_token in step 1.
cancel_operation
ChatGPTOnly after the user agrees: fence out remaining work and release its unused reservation. Completed charges remain. Refuses while a worker/request is active; inspect get_operation first.
change_video_plan
ChatGPTSend the user's answer to the Creative Director's question, a change to the plan before it is made, or a change to the finished video ("make the logo bigger", "use a calmer voice"). The Creative Director re-plans, which costs a few credits; the change itself is priced and approved with approve_video_plan like the first version. Then poll get_video_plan.
clone_voice
ChatGPTRegister an uploaded audio sample as a new zero-shot voice. Ask the user to confirm permission to clone and use the speaker’s voice; only then pass consent true. Synchronous: returned active voice is ready, with no training job. Plan clone allowance applies. Repeating the same source asset reuses the clone. Registration is free; narration generation requires a separate approved quote. Select an existing clone via list_voices instead of creating it again.
create_character
ChatGPTCreate a reusable AI character for videos and UGC ads, from a description and/or 1–8 library reference images (list_library type image). Free. CONSENT: if reference images show a real person, ask the user to confirm they have that person's consent and pass consent: true. Plan limits on the number of characters apply.
create_character_image
ChatGPTSPENDS CREDITS (the quote's amount). Only after the user agreed. Returns a generation id; poll get_character_image every 10 seconds.
create_presenter_preview
ChatGPTSpends the quoted credits. Only after approval. Reuse the same quote/idempotency key after a timeout; a pending response means wait, not start a replacement.
create_ugc
ChatGPTStarts the takes an estimate_ugc quote described. SPENDS CREDITS and uses monthly takes. Only after the user has seen the quote and agreed. Returns one video id per take; poll each with get_video_status and fetch with get_video_result.
create_video
ChatGPTStarts making the video that estimate_video quoted. SPENDS CREDITS, up to the quote's max. Only call after the user has seen the quote and agreed. Returns immediately with a video id and status "generating"; poll get_video_status every 15–30 seconds. Rendering takes a few minutes. The same quote_id cannot start a second video.
estimate_character_image
ChatGPTPrice one generated image of a character (a new look, or a new reference photo). Returns a quote_id (10 minutes). Cheaper without a reference photo; with one, the image is generated to match it.
estimate_character_reference_edit
ChatGPTPrice an AI edit of the character's uploaded reference photo: same person, pose and framing, changed only as instructed (outfit, background, hair, expression, product in hand). The result becomes the new reference photo unless set_as_reference is false. Returns a quote_id (10 minutes); generate it with create_character_image and poll get_character_image. Refuses with no_reference when the character has no photo yet.
estimate_presenter_preview
ChatGPTQuote a generated portrait inspired by a character. Ask for likeness rights/consent first. Not the final video identity or a guaranteed match.
estimate_retry
ChatGPTGet a new authorized ceiling for retrying failed composable generation. Resolve any prior uncertain operation first. Show this quote to the user before retry_video.
estimate_ugc
ChatGPTPrice a plan from plan_ugc and get a quote_id (10 minutes). mode "composed": each shot generated and cut together, with one or more characters from list_characters (needs character_ids unless every shot is b_roll). mode "one_shot": a single continuous AI presenter take from a description or a character. CONSENT: before calling, ask the user to confirm they have the right to use any real person's likeness or voice in the ad, and pass consent: true only if they say so. Returns credits, takes used against the monthly allowance, and can_afford.
estimate_video
ChatGPTFor WyvStudio Classic, when the user asks for it. Price a scene-by-scene video before making it. Returns a quote_id with the credit range (min/max), scene count, balance, whether the workspace can afford it, and "chosen": the brand kit, channel, niche, character, music and voice it resolved to, by name. Show the quote and the choices to the user; create_video needs the quote_id and the quote expires in 10 minutes. You may pick styles, kits, channels, niches and voices yourself from the list_* tools when the user has not named one. Nothing is built or charged by estimating.
export_video
ChatGPTRender a new export of the current state, in one or more aspect ratios. Uses the plan's export allowance, not credits. Poll get_video_status; get_video_result returns the newest completed export.
get_asset
ChatGPTRead an owned asset and its transcription status. To attach narration, propose_edits with op use_narration, scene_id, asset_id and mode audio_only (keep script) or audio_and_script (replace script with completed transcript). Show the proposal before applying it.
get_asset_preview
ChatGPTA JPEG preview of any image or video asset in the library or on a generation result (a frame, for video). Show it inline. Spends nothing. The result carries the image and a preview_url (a JPEG link valid for 12 hours) for clients that show pictures by URL.
get_capabilities
ChatGPTWhat this workspace can make and what it costs: plan, credit balance, limits, supported inputs, visual modes and per-scene prices. Call this first, and again if a create is refused for credits or limits.
get_character_image
ChatGPTStatus of a character image generation: generating, completed (with the image asset) or failed.
get_character_preview
ChatGPTA JPEG preview of a character: its reference photo, or its latest generated image when it has no photo. Show it inline. Spends nothing. The result carries the image and a preview_url (a JPEG link valid for 12 hours) for clients that show pictures by URL.
get_edit_history
ChatGPTWhat undo and redo would do next (undo_label, redo_label) and the latest edits, each with who made it (user, assistant, cruise). Classic videos only (numeric video id); a planned video has versions instead. Free.
get_operation
ChatGPTRead execution progress, known results and accounting state by the original quote or plan id. Safe after a timeout. This does not restart work or release credits. needs_attention means investigate; do not create replacement paid work. Media readiness is checked separately with video/generation status.
get_options
ChatGPTOption keys for estimate_video: visual styles with labels, animate tiers, pacing, aspect ratios, platform targets, languages, tone examples, audiogram settings. Read once per conversation.
get_post
ChatGPTStatus of a post made with publish_video: scheduled, publishing, published (with post_url) or failed. Omit post_id to list the video's posts.
get_project
ChatGPTThe full editable state of a video: revision, project settings, ordered scenes with every setting and a readiness block (script, visual, voice, animation, in-progress, errors, locked fields), hook options, and the latest export with its freshness. Read this before proposing edits; the revision must match when you apply.
get_scene_preview
ChatGPTA JPEG preview of one scene: its still or stock visual, or a frame of its animation (default: the animation when one exists). Show it to the user inline so they can judge the scene without opening the app. Spends nothing. The result carries the image and a preview_url (a JPEG link valid for 12 hours) for clients that show pictures by URL.
get_ugc_allowance
ChatGPTWhether UGC ads are enabled on this plan, takes used and remaining this month, and the per-run and per-take limits.
get_video_plan
ChatGPTWhere a planned video stands, with what to do next. state is one of: planning (check again shortly), question (the Creative Director asks the user something: ask them and send the answer with change_video_plan), plan_ready (show the user the plan; get the price with approve_video_plan), look_ready (show the user the images; approve them with approve_video_plan and look_token), building (check again in a minute or two), ready (preview_url to watch; preview links last about 45 minutes, so call again for a fresh one), needs_attention (what went wrong and how to continue). app_url opens it in WyvStudio.
get_video_result
ChatGPTThe selected completed MP4 as a private, time-limited download link (download_expires_at), plus duration, aspect ratio, credits spent and the project_url. The default selects the newest export, even while pending/failed. Stale or superseded exports need explicit export_id and allow_stale=true after user approval. The link is for the workspace only; nothing is made public.
get_video_status
ChatGPTProgress of a video: status is generating, exporting, completed, needs_export or failed, with the current stage, credits spent so far and a project_url the user can open in WyvStudio. When completed, call get_video_result for the file. When failed, read failure.message; retryable means the user can retry from the dashboard.
list_brand_kits
ChatGPTThe workspace's brand kits (colours, fonts, default caption style and voice). Pass an id as brand_kit_id.
list_caption_presets
ChatGPTThe workspace's saved caption presets (font, colours, position, animation). Use with the editor caption settings.
list_channels
ChatGPTThe workspace's channels (defaults for language, platforms, voice, captions, brand kit). Pass an id as channel_id; its defaults apply.
list_characters
ChatGPTThe workspace's reusable AI characters. Pass an id as character_id to feature one in the video.
list_exports
ChatGPTEvery export of a video, newest first, with status and download links for completed ones. Older exports do not contain newer edits.
list_library
ChatGPTThe workspace's uploaded assets by type: images (for source_type images or as references), music tracks (for music_asset_id), videos (footage and demo clips), audio (narration/samples), sound (SFX). 50 per page; use q to search titles.
list_niches
ChatGPTContent niches with default style, tone and music mood. Pass an id as niche_id; its defaults fill anything you leave out.
list_social_accounts
ChatGPTThe YouTube, TikTok, Instagram and Facebook accounts connected to this workspace, with ids for publish_video, and whether this plan can publish. Accounts are connected in the app.
list_video_plans
ChatGPTThe workspace's newest planned videos with each one's state, newest first. Use an id with get_video_plan, change_video_plan or share_planned_video.
list_video_templates
ChatGPTFinished videos the user can start from: each with its kind (offer ad, app showcase, explainer, UGC ad, announcement, from your footage), shape, length, what it asks for and a watch_url to show the user. Start one with plan_video_from_template. in_plan false means the user's plan does not include that template. follow_options lists how closely a template can be followed.
list_voices
ChatGPTThe voices a video can be narrated in: WyvStudio's catalogue plus this workspace's own voices and clones, each with language, gender and credits per scene. Pass a voice id to estimate_video as voice_id. Omit it for the default voice.
plan_ugc
ChatGPTClassic UGC Ads, for takes to test side by side (several actors or hooks). For a single UGC ad use ugc_brief (the UGC director). Turn a script or a brief into a shot plan for a UGC-style ad: shots with kind (on_camera, b_roll, reaction), narration, seconds and visual direction, plus the format it chose. Free. Pass the returned format and segments to estimate_ugc unchanged. Formats: direct_camera (one continuous talking take), demo, story, reaction, text_led; "auto" lets the planner pick. Optionally ask for alternate openings with variants_count.
plan_video
ChatGPTPlans a short branded video or ad. Describe a short branded video and WyvStudio's Creative Director plans it: concept, scenes, script and voice, in the workspace's brand. Planning starts at once and costs a few credits; nothing else is charged until the user approves a price with approve_video_plan. Write the brief in the user's words, with the product, offer, audience and any exact lines. Then poll get_video_plan (planning takes a minute or two). Files: upload with upload_asset and pass their ids. A TikTok, Reel, YouTube or X link in reference_url makes the video in that clip's style; a product page link gives facts and look.
plan_video_from_template
ChatGPTStarts planning a video from a template (list_video_templates) for the user's product: what it is in their words, with any offer (a link is kept as text, not opened), how closely to follow the template (exact: the same video with their product, words, colours and photos; similar: its format, look and pacing, their own story; inspired: just the idea), the shape, and their photos (upload with upload_asset first). Planning starts at once and uses a few credits. Then get_video_plan, and approve_video_plan with the user's yes, as for plan_video.
prepare_delivery
ChatGPTPreflight public sharing, an approval request or scheduling in the app (publish_video posts directly; use this for the in-app scheduler or approvals). Requires the current project revision and explicit completed export id. Returns an authenticated editor link and confirmation checklist only. DOES NOT publish, send mail, create a public link or schedule a post. The user must review the export and confirm recipient/destination in the app. The app does not automatically select the supplied export. Export/download support is not publishing support.
preview_voice
ChatGPTFree fixed preview. For cloned voices this plays the original SOURCE SAMPLE, not newly synthesized clone audio. To hear generated narration, quote regenerate_voice on a scene. voice_id is the string id from list_voices.
publish_video
ChatGPTPOSTS TO AN EXTERNAL ACCOUNT and cannot be undone. Posts a completed export now, or schedules it for scheduled_at. Before calling: read the project for its current revision, pick the export id from get_video_result, pick the account from list_social_accounts, and show the user the account, caption, title, visibility and time. Set confirm=true only after the user explicitly approved that exact post. Returns a post id; poll get_post until published (post_url) or failed. Spends no credits.
redo_edit
ChatGPTBrings back the edit most recently undone (redo_label from get_edit_history). Free. Not available after a new edit was made since the undo.
retry_video
ChatGPTRetry generation of a failed video, or resume the failed parts of one. Requires an estimate_retry quote and user approval. Uses the original idempotency key on transport retries.
save_voice
ChatGPTSave an accessible catalogue voice in this workspace, or return its existing profile. Free. Does not clone a speaker or accept arbitrary provider ids. The returned voice_profile_id is the numeric editor profile id; id is the string narration voice id.
share_planned_video
ChatGPTA link anyone can watch the finished video at (saved to the library first). Pass version for an earlier one; enabled false turns the link off.
share_video
ChatGPTGives the user a public link (no login) to watch the video's latest completed export, or turns that link off. Reversible; spends no credits. Needs a completed export first. Tell the user anyone with the link can watch.
ugc_brief
ChatGPTStart a UGC ad with the user's brief (product, audience, angle, any script, how names are said). The director answers with one question (answer it with ugc_reply, offering suggested_answers) or a pitch: what the video shows, its script, the presenter and model, and the credits. Free. Show the pitch to the user; change it with ugc_reply; make it with ugc_make.
ugc_make
ChatGPTMakes the video the pitch describes. SPENDS the pitch's credits, held as it starts and given back if it does not deliver. Only after the user has seen the pitch and price and said yes, and confirmed they have the rights to any real person's likeness or voice (consent). message_id is the pitch's. model picks another of the pitch's other_models. music adds a music bed to a POV hook or reaction (+2 credits). Then poll ugc_status.
ugc_reply
ChatGPTAnswer the director's question, or ask for changes to the pitch ("make her older", "shorter", "say Lumora as loo-MOR-ah"). Returns the next question or a revised pitch. Free.
ugc_status
ChatGPTThe chat's last director message and every video it started: status (generating, ready, failed) and, when ready, a link to watch it.
undo_edit
ChatGPTPuts the video back to before its latest edit, whoever made it. Call get_edit_history first and tell the user what will be undone (undo_label); undo only when they want that. Free: credits are not refunded or charged, generated files are kept, so redo_edit brings it back. Refused while something in the video is still generating. The export becomes out of date, so re-export before delivering.
update_character
ChatGPTChange a character's name, description, references, consistency method or identity strength. Free.
upload_asset
ChatGPTUpload actual file bytes as base64, at most 8 MiB decoded. Supports JPEG/PNG/WebP, MP3/WAV/M4A/OGG/FLAC, MP4/MOV/WebM. Never invent bytes or pass a URL. For larger files, use authenticated multipart POST /api/developer/v1/assets (100 MiB limit). Returns asset id; poll get_asset for transcription. Upload is free; video generation is separately quoted. Client must have access to the file bytes.