Plan, render, and finish image and video ads. Long renders run as jobs you poll.
MOTION GRAPHICS IN ONE CALL
make_motion_film#
Make a motion graphics video
MOTION GRAPHICS and ANIMATED VIDEO in one call: kinetic typography (animated text), a logo animation or intro, a product launch film, an animated social cut. MOVING PICTURES are the default for launch, product and social: in each scene with a picture, one thing physically happens (a seed splits open, an eye opens, the view travels through a forest), filmed by an image-to-video model, with the type, transitions and the music's beat put on top; a few minutes, priced per shot, and with no pictures given each scene paints its own. moving:false, and always for type and logo, makes it in code with no video model: type, pictures and drawn graphics filmed by a moving virtual camera, a 1080p MP4 in about a minute, billed for its compute only. Pick it for 'animated video', 'motion graphics', 'kinetic text', 'text animation', 'logo animation', 'logo intro', 'animated explainer' asks. recipe: 'type' (every line its own animated card, no picture needed), 'logo' (the logo assembles out of dots and settles, the name and tagline land under it), 'launch' (30s 16:9), 'product' (15s), 'social' (15s 9:16). Or `spec`, the whole film as JSON (help:true returns the language). STEPS: without confirm it is a FREE quote that gives both prices (length, the music's tempo; the spec in structuredContent): say both; preview:true is a 1-credit contact sheet of the still version; confirm:true renders. You may write `moves` yourself, or the film's own planner writes them for a few credits. Only the user's or the brand's words appear: never invent a claim, number or review. projectUrl = a past film's url returns its saved spec to edit and render again.
| Parameter | Type | Description |
|---|
recipe | "type" | "logo" | "launch" | "product" | "social" | type, logo, launch, product or social; help:true lists the recipes |
hook | string | opening line; '*word*' = italic accent |
lines | string[] | more short lines, in order |
tagline | string | line shown under the headline or logo |
name | string | default: the saved brand's |
logo | string | logo image: https, upload_file URL or Library id; default the brand's |
images | string[] | pictures, hero first (https, upload_file URL or Library id) |
size | "16:9" | "9:16" | "1:1" | "4:5" | frame shape: 16:9, 9:16, 1:1 or 4:5 |
seconds | number | logo 4-10, others 6-60 |
mood | "elegant" | "epic" | "upbeat" | "hype" | "calm" | "tense" | "playful" | music and pace |
music | string | 'off' = silent |
theme | "light" | "dark" | logo: dark for a light logo |
energy | number | how much the film keeps moving, 0 to 1; 0 films exactly what is written |
moving | boolean | true: one thing physically happens in each picture, filmed by a video model. false: stills moved by a virtual camera, far cheaper. Default true for launch, product, social |
moves | object[] | per scene, what happens in its picture; omit and the planner writes them |
brief | string | what the film is about, for the planner |
model | string | image-to-video model id from hermoso_capabilities; default is the best value for short shots |
resolution | string | the moving shots: 720p or 1080p (default) where the model has them |
spec | object | the whole film as JSON, from a quote or a saved film; help:true shows the spec language |
projectUrl | string | a past film's url; returns its saved spec to edit and render again |
help | boolean | true returns the spec language and recipes; renders nothing |
preview | boolean | true renders a 1-credit contact sheet to approve before the full render |
confirm | boolean | true renders the film for real credits; without it you get a free quote |
finish_video#
Finish video
Post-process an EXISTING rendered video (its served mp4 URL) with the proven direct-response 'reviewer' finish and/or a film-grain pass — no AI model, ~30s, billed for its compute only. pills=true composites a header pill (e.g. '10/10 would buy again'), a brand-accent sub-pill, and 3-4 green-check proof pills cascading in on the beat (YOU author the copy: header ≤40 chars, sub ≤34, each point ≤44 — concrete real benefits, never fabricated stats). grain=true applies a subtle camera-grain finish that makes photoreal AI renders look phone-shot ('less AI') — works alone or with pills. Returns a NEW video; the original is untouched.
| Parameter | Type | Description |
|---|
videoUrlrequired | string | the served URL of the video to finish (from a previous render/job) |
header | string | header pill copy, ≤40 chars (required when pills is on) |
sub | string | accent sub-pill copy, ≤34 chars (usually the product/brand) |
points | string[] | 3-4 proof points, ≤44 chars each |
accent | string | brand accent hex for the sub-pill |
pills | boolean | default true — set false for a grain-only pass |
grain | boolean | default false — anti-AI film-grain finish |
post_edit#
Post-production edit
MECHANICAL post-production on an EXISTING video (URL): ordered primitives run by ffmpeg in seconds, ~2 credits flat, NO AI model, as a NEW video. Ops: a branded end card (adds its seconds), trim, speed (0.5-2x), mute (whole or a window), audio_gain (-20..+6 dB), fade_out, music (a bed UNDER the clip, its own sound kept and ducked under: omit track = a free library track picked by mood, no attribution; or track = an audio link: an upload_file URL, a find_sound or generate_sfx link, a video post's sound; track 'generate' composes it, paid, ONLY when the user asks; start/end, db, replace), voiceover (text spoken OVER it, its sound ducked; ~2.5 words/s; voice female|male; +~1 credit), watermark (brand logo), grain (anti-AI), text (timed words in a native look: style 'tiktok-classic' default / 'clean-minimal' / 'note-style' or a textStyle; start/end), join (this video FOLLOWED BY clips[]: Library URLs, direct files or public post links, as one 1080x1920 video, loudness matched). Presets are shortcuts: text/watermark take any x/y, grain any amount, join any ffmpeg transition, a bridge any sound link. 'A viral hook, then our clip' = videoUrl: the hook's post link + [{op:'join', clips:[{url: ours}], bridge}], and it ALWAYS gets a bridge unless the user asks for a bare cut: {kind:'impact'} cuts the hook just before its payoff (found from the footage; cutAt overrides) and lands our clip on a punch-in and flash, with the payoff sound FROM THE HOOK ITSELF: its own audio carries across the cut, else one generated from its frames (up to 8 credits), else a neutral impact. {kind:'text', text, then?} only when the user asks for words over the cut. No voiceover bridge: have our clip's host say the connecting line. matchCut = where our clip starts. ANY OTHER EDIT, op or bridge (whip, zoom, freeze, wipe, split screen, generated shot) is edit_timeline: free keyframes, any size. NEVER generate_video/render_ad for these.
| Parameter | Type | Description |
|---|
videoUrlrequired | string | the video to edit: a render / Library URL, a direct file, or a public post link |
opsrequired | object[] | the ordered edit plan (max 6 ops) |
brandName | string | override the workspace brand name |
domain | string | override the brand website |
accent | string | override the brand accent hex |
dryRun | boolean | true = return the estimated credits this edit reserves and run nothing |
edit_timeline#
Compose an edit (timeline)
Compose ANY edit or transition yourself; there is no preset list. Segments on an output timeline (later ones drawn on top; overlapping ones ARE the transition), each animated by keyframes, plus your own HTML overlays and masks, compiled server-side into one render. Whip pan, zoom through, push, spin, speed ramp, slow motion, freeze frame, reverse, flash, J-cut / L-cut, circle or shape wipe, split screen, picture in picture: all composed from the fields below. Local render, the flat post_edit price (~2 credits, overlays included); a `generate` segment (a paid generated transition shot) only when the user explicitly asks for one. LOOK FIRST AND AFTER: video_frames(url, start, end, fps) shows exact frames free, so find the moment (the second the egg tips) before you cut, and check the seam of what you rendered before you call it done. SOURCES: src is 'this' (videoUrl) or any Library / render URL, direct file or PUBLIC TikTok / Reel / Facebook / X / YouTube post link (a viral hook's link works as is). in/out are SOURCE seconds; out:'payoff' cuts just before the hook's payoff, found from its motion. AUDIO: audio.tail:'payoff' carries the hook's OWN payoff sound across the cut (the egg's real splat over our clip); tail seconds = an L-cut; lead = a J-cut; gain dB or keys; mute. A VIRAL HOOK + THEIR PRODUCT: start from the hook. A clip matched to an unrelated hook never reads as one video, so write the clip AFTER the hook for it: a linking script + shot brief (the first line answers the hook, e.g. 'still waiting for the egg to land... anyway, come check out our restaurant'; what to film so it follows on; 5-15 s; then the pitch). The user records it, or you generate it (render_ad / generate_video, cost quoted first, on their OK); then join here: the hook with out:'payoff' and audio.tail:'payoff', then their clip. Match an existing unrelated clip only if they insist. A {generate:{prompt, seconds 3-8}} segment (a generated transition-only shot, paid, postEditTimeline) is never suggested; build it only when they explicitly ask for one. LINK FIRST: an effect alone never connects two unrelated clips; the link comes from what is in the frames. (1) Match cut, the default: video_frames (with its MOTION readout) on the hook's last second and across the other clip; pick the out-point AND the in-point (in: seconds, not always 0) where a motion direction, a screen position or size, a shape, a surface, a gesture or a gaze carries across, then ride the effect on that shared motion. (2) Its host names the hook in the first line. If the two share nothing, say so and offer the follow clip made for the hook. PRO, NOT IMOVIE: ease every curve (never linear on a move); keep the picture filling the frame through a move (scale up while it moves: two frames sliding side by side with a seam is the amateur tell); hide the handoff under the fastest, blurriest frames; carry direction into the next shot; cut on motion; end every effect cleanly; 0.2-0.6 s in total; a sound whose peak lands on the handoff (sfx whoosh at handoff minus 0.45 s, or the hook's own payoff sound). Moving segments get a real shutter blur automatically (motionBlur). EVERY SEAM IS MATCHED AUTOMATICALLY, hard cuts too: each cut is measured and the incoming clip graded (exposure, white balance, black level), grained UP (never smoothed) and softened while it moves toward the outgoing one; the reply gives before/after deltas per seam. match (timeline: every cut; segment: the cut into it): 'auto' default, 'off' for a deliberate contrast, or {grade, level, grain, blur: false to skip one, strength 0-1}; a segment's own constant exposure / contrast / saturation replaces the automatic grade. EVERY STITCH CHANGES THE SHOT: where two different clips (or two non-contiguous moments of one) meet at the same framing, the incoming one gets a simple crop of the same footage, varied: zoomed in on the subject, back out to the wide, or reframed off-centre (reframe: 'off' or the step 1.1-1.5; a segment with its own framing, a card or a transition is left alone). Still yours: subject size and headroom (scale it, never a jump from a third of the frame to two thirds) and sound (a 0.25-0.5 s J/L-cut, never a sonic wall). A clip placed after a hook gets a BUDGET (total - intro = its surviving window, and what was dropped). The plainest thing that links wins: a straight cut on action beats a decorative effect; over 0.5 s is too long in anything under 20 s; never flash more than 3 times a second. RECIPES (c = the cut second, adapt freely): whip pan: A over its last 0.22 s x 0 to -0.22, scale 1 to 1.35, mblur 0 to 220, all ease in; B overlap 0.08, opacity 0 to 1 over 0.08, x 0.22 to 0, scale 1.35 to 1, mblur 220 to 0, all ease out over 0.3 s; whoosh at c-0.45. Zoom through: A over its last 0.35 s scale 1 to 3 ease in anchored on the object, blur 0 to 10; B overlap 0.12, opacity 0 to 1, scale 1.5 to 1 and blur 10 to 0 ease out over 0.4 s. Cut on action: A out ON the motion, B scale 1.08 to 1 ease out over 0.25 s, audio.lead 0.2. Speed ramp: speed [{src:t0,v:1},{src:t0+0.25,v:0.3}] then [{src:t1,v:0.3},{src:t1+0.1,v:2}] into the cut. Circle wipe: B overlap 0.5 + overlays [{mode:'mask', segment:1, start, end, html: a white div whose clip-path circle grows via @keyframes}]. Card (picture in picture: a proven ad playing in a rounded card over the host watching it, any length): the host segment full frame, then the clip ON TOP with at:0, fit:'contain' (crop to reframe it), scale ~0.6-0.7, y ~0.12, radius ~0.04-0.06; a card is not a cut, so it is never graded toward the host; duck it under the host's first line with audio.gain keys (the host's voice leads the switch) and end it on a hard cut at a sentence break. SELF-CRITIQUE: the reply carries a vision REVIEW of each seam (pro / ok / amateur, linked or not, with fixes; about 2 credits, review:false skips it) and the seam frames. When it says ok or amateur, fix what it names and re-run the same sources (twice at most) before presenting; on a re-run give a generated segment {src: its URL, between: true} so it is not paid for twice. Then look at the WHOLE result once with video_frames, not only the seams: the first frame is not black or frozen, no dead air over ~0.3 s at the head, no lone black, flash or repeated frame at a cut, and nothing static for more than ~4-5 s (recut it or add a re-hook). FOLLOW-UPS ('cut earlier', 'no splat', 'whip pan instead', 'use the second hook') re-run this with the SAME sources and the one change; the result echoes the resolved timeline (e.g. the found payoff cut) to edit from. Refusals are free and name the field.
| Parameter | Type | Description |
|---|
videoUrl | string | the video 'this' refers to (optional when every segment names its own src) |
segmentsrequired | object[] | the clips on the output, max 12, later ones on top. Every animated field (scale x y rotate opacity exposure blur mblur brightness contrast saturation, audio.gain) is a constant or keyframes [{t: seconds into this segment | src: a second of the source, v, ease: linear|in|out|inout|hold}]; x and y are in canvas widths / heights, rotate in degrees, mblur in px along mblurAngle |
overlays | object[] | HTML/CSS overlays animated with @keyframes, each shown between its start and end |
sfx | object[] | sound effects placed on the output timeline |
size | string | canvas: '9:16' default, '1:1', '4:5', '16:9', any 'W:H' (1:3 to 3:1, on a 1080 short side) or exact 'WxH' pixels |
fps | number | the frame rate, a whole number from 24 to 60 (24, 25, 30, 60 are the usual ones). Leave it out: the canvas takes the rate of its own footage (the rate of most of it on screen), so no frames are invented; a faster clip is thinned, a slower one that does not divide it is motion-interpolated |
motionBlur | boolean | default true: anything that moves gets a real shutter blur along its path |
review | boolean | default true: a vision read of each seam (about 2 credits) comes back with the render, with the seam frames |
match | "auto" | "off" | object | every cut: 'auto' default |
reframe | "auto" | "off" | number | every cut: 'auto' default |
video_frames#
Look at video frames
LOOK at a video's exact frames, free: one contact-sheet image of the frames from start to end at fps (e.g. a seam, 3.0-3.8 s at 10 fps) or at the listed times, tiles in reading order with each tile's second listed. Use it to find a moment before an edit and to check a render's seam after it. Takes a Library / render URL, a direct file or a public post link (a TikTok / Reel / Facebook / X post link is opened through one paid lookup, 1 credit; a file is free). SAVE STILLS: save:true returns full-size still images (frame grabs, up to 8) as URLs instead of a contact sheet, picked by times or by clips (numbered at the video's hard cuts, -1 = the last): a before / after from someone's own footage, a cover, a product shot. Compose with those URLs (make_template_ad template 'custom', a post) with no AI.
| Parameter | Type | Description |
|---|
urlrequired | string | the video |
start | number | window start in seconds |
end | number | window end in seconds |
fps | number | frames per second in the window (default ~16 frames across it) |
times | number[] | exact seconds instead of a window (max 48; max 8 with save) |
save | boolean | true = save the frames at times / clips as full-size stills and return their URLs |
clips | number[] | save: one still from the middle of each numbered clip (split at hard cuts; negative counts from the end) |
fix_beat#
Fix a video beat
Surgically re-render ONE time window (1.5-8s) of an existing rendered video and splice it back on the VIDEO TRACK ONLY — the rest of the video and ALL audio stay byte-identical. Use when one beat/shot is broken ('the shot at 8 seconds glitches') and a full re-render would waste the parts that worked; bills only the replacement clip's seconds (~1/3 of a full render). Do NOT pick a window covering spoken dialogue (a video-only splice under speech breaks lip-sync) — pass speechWindows to enforce this. A FINISHED VIDEO-BLOCKS FILM (make_explainer's explainer or faceless channel; get_job says it is editable) is edited ONE BLOCK at a time instead: pass `job` (its job id) and `block` (1-based) or `atSeconds`, with `prompt` for a different shot and/or `line` for new narration words. Only that block is re-rendered and/or re-read; every other block, take, the music and the captions are the film's own and stay aligned. It is priced as that block alone and charged exactly what it quotes (dryRun). The original film is kept; a new film comes back, and it can be edited again.
| Parameter | Type | Description |
|---|
videoUrl | string | the served URL of the master video to fix (not needed with `job`) |
startSeconds | number | window start in seconds (not needed with `job`) |
endSeconds | number | window end in seconds (window 1.5-8s; not needed with `job`) |
prompt | string | what the replacement footage should show — describe the shot, matching the master's style. With `job`: the change to that block's picture, in words |
job | string | a finished video-blocks film (explainer / faceless channel): its job id. Edits one block of it instead of splicing a window |
block | number | with `job`: which block, 1-based (block 3 = 20-30s of a film of 10s blocks) |
atSeconds | number | with `job`: the moment in the film instead of `block` ("the line at 0:12" = 12) |
line | string | with `job`: the new narration for that block, the exact words to say (said as written, never rewritten; refused for free when it cannot fit the block) |
refImage | string | optional product/style anchor image URL |
speechWindows | number[][] | [[start,end],...] windows with spoken lines — the fix window must not overlap these |
dryRun | boolean | true = return the estimated credits this fix reserves and render nothing |
CONTENT FACTORY
resume_job#
Resume a stopped film
Finish a video-blocks explainer or faceless-channel film (make_explainer) that STOPPED partway: a block the video model would not render, or a server restart. What it already made is kept (the script, the style key, the narration and every block that rendered), so this renders ONLY the missing blocks and re-assembles the same film, with the same topic, look, voice, length and options. It reserves credits only for what is missing and never charges again for what was kept. get_job and list_jobs show which jobs can be resumed and which blocks are kept. Quote it with dryRun first and tell the user the number. A finished film is not resumed: to redo one block of a finished film, use fix_beat with its job id.
| Parameter | Type | Description |
|---|
jobIdrequired | string | the id of the film that stopped (job_...), as get_job or list_jobs shows it |
dryRun | boolean | true = return the credits the resume reserves and render nothing |
make_series#
Make a series of faceless short videos (Content Factory)
CONTENT FACTORY: turn ONE topic into a SERIES of faceless short videos (narration over pictures, no presenter), optionally in the STYLE of a trending reference video. Give `topic` ("make a video about…"), `episodes` (1-10, default 1) or your own `episodeTitles`, `durationSeconds` (20-120 per episode, default 30) and optionally `reference` (a TikTok / Reel / YouTube Short / Facebook / X link or a video file URL whose look, pacing and opening hook every episode copies, with plain subtitles only if the reference burns its own; never its words or characters). Find a trending reference with search_tiktok / search_instagram / search_youtube when the user wants one. THREE STEPS, ALWAYS IN THIS ORDER: (1) call with no `confirm` for a FREE quote of the whole series (per episode and total); (2) optionally `planOnly:true` to see the episode titles and the style card first (a small planning charge); (3) `confirm:true` (pass the `plan` from step 2 to reuse it) queues every episode and returns their job ids; poll get_job. To make MORE of a series later, pass its returned plan as `moreOf`: same style, no episode repeated, the reference not watched again. Each finished episode can be scheduled with this tool again: pass `jobIds` plus `schedule` {channels, at, everyHours, timezone} and it books one post per finished episode, spaced `everyHours` apart (default 24). Captions follow the reference (on if it burns words on screen) unless `captions` says otherwise.
| Parameter | Type | Description |
|---|
topic | string | what the series is about, in the user's words |
episodes | number | how many episodes, 1-10 (default 1) |
episodeTitles | string[] | your own episode titles, in order (sets the episode count) |
durationSeconds | number | length of EACH episode, 20-120 seconds (default 30) |
reference | string | a video link whose style every episode copies |
aspectRatio | "9:16" | "16:9" | "1:1" | default: the reference's shape, else 9:16 |
style | string | override the look in words (e.g. "flat 2D cartoon") instead of the reference's |
captions | boolean | burn subtitles of every spoken word. Default: on only when the reference itself burns its spoken words as subtitles, otherwise off; nothing else is ever put on screen (no app screens, URLs, cards or stickers) unless the user asks |
voice | string | narrator: 'female' or 'male' (default follows the reference), or any narration voice name make_explainer takes |
format | "explainer" | "faceless_channel" | renderer lane: 'explainer' (default; exact length) or 'faceless_channel' (2K, whole 10s blocks) |
planOnly | boolean | write the episode plan and style card, render nothing (a small planning charge) |
plan | object | the `plan` a planOnly call returned, to run it without planning again |
moreOf | object | MORE EPISODES: the `plan` an earlier call returned. Keeps its style and length, writes new episodes only |
confirm | boolean | REQUIRED true to start rendering (real spend). Without it you get a free quote |
jobIds | string[] | SCHEDULE MODE: the episode job ids to schedule (finished ones are booked) |
schedule | object | SCHEDULE MODE: where and when the first episode posts; the rest follow every `everyHours` (default 24) |
postCaptions | string[] | SCHEDULE MODE: one post caption per episode, in order (default: the episode title) |
make_effect#
Run a one-click effect on a photo
ONE-CLICK EFFECTS, the same ones as the /tools pages: a photo goes in, a styled picture comes out, and most can then become a 5-second clip. Plush toy, 3D figure, mascot, comic book, pixel game, billboard ad, giant product, bullet time, packshot, outfit swap, headshot, relight and many more. Name no `effect` for the free list. `effect` alone: what it takes. `effect` + `images`: a free quote; add confirm:true to make the picture. Then `effect` + `still` (that picture's URL): a free quote for the clip; confirm:true makes it. `describe` adds anything of your own. For a look not on the list use generate_image. A real person's photo follows the same likeness rules as every render.
| Parameter | Type | Description |
|---|
effect | string | effect id from the list |
images | string[] | its pictures, in the order listed: URL, local path or Library id |
options | object | its listed options, e.g. {material:"knit"}; "custom" means use `describe` |
text | string | a line printed exactly, on an effect that takes one |
describe | string | your own words: added to the look, or the custom choice |
aspectRatio | string | one of its listed shapes |
still | string | CLIP STEP: the finished picture to animate |
speech | string | CLIP STEP: a line said in the clip, on an effect that speaks |
confirm | boolean | true = run it (real spend); without it, a free quote |
product_sizzle#
Product sizzle (music-led)
Render an 18-30s music-led PRODUCT SIZZLE: ONE 15s Seedance 2.5 hero clip of the product, diced into fast cuts and intercut with typeset spec/CTA cards on a brand-coloured grain background, mixed to a music bed. Faceless by design — no people, no voiceover, no spoken lines; the cards carry every word, so nothing is left to a video model's spelling. Pass a real packshot as refImage or the label will not be yours. EXPENSIVE — the hero clip is the only paid leg and it is a full 15s Seedance 2.5 render: ≈870 credits at the DEFAULT 1080p, ≈360 at 720p, ≈170 at 480p; a 4k ask renders on Seedance 2.0, the only Seedance tier with 4k, ≈2,360 (call hermoso_capabilities for the live seedance-2.5 per-duration numbers; the dicing and the cards are free, and the music bed is included in these figures). Confirm the spend with the user before calling. For a talking/UGC ad use render_ad or generate_avatar; for a cheap deterministic format use make_template_ad.
| Parameter | Type | Description |
|---|
promptrequired | string | what the sizzle should show — the product, the setting, the look |
seconds | number | finished length, clamped to 18-30s (default 25). The PAID hero render is always 15s regardless — this only changes how the cuts and cards are packed |
refImage | string | product packshot URL that anchors the real label — strongly recommended |
aspectRatio | string | '9:16' default; anything the Seedance row that renders it does not list falls back to 9:16 |
resolution | "480p" | "720p" | "1080p" | "4k" | hero-clip resolution and therefore the whole cost — DEFAULT '1080p' (≈1,040 credits); '720p' ≈470, '480p' ≈220, '4k' ≈4,130 |
specs | string[] | up to 4 spec lines for the typeset cards, ≤26 chars each |
cta | string | closing CTA line, ≤30 chars |
brandName | string | brand name on the cards — defaults to the workspace brand |
musicMood | string | music-bed mood, e.g. driving / cinematic / upbeat |
style | "hypermotion" | "product_2d" | "typography" | "dark_minimal" | "color_pop" | "mixed_media" | "saas" | "product_showcase" | the LOOK of the sizzle (same price for every look): hypermotion (Fast cuts, crash zooms and speed ramps), product_2d (The real product with playful hand-drawn 2D animation around it), typography (Product framed by huge bold letterforms in the brand colours), dark_minimal (Moody, premium, a single hard light on black), color_pop (Bright saturated colour, glossy, joyful), mixed_media (Editorial collage: paper, cut-outs and texture around the product), saas (For apps and software: floating screens, light trails, particles), product_showcase (Hero commercial: ingredients, splashes and a clean pack shot). Default hypermotion. |
generate_video#
Generate video
Use this when the user asks for a video clip, b-roll or a shot from a description, or names a video model. For a finished video ad, Reel, TikTok ad or UGC video for their business, use render_ad. It renders one continuous clip on a real video model and returns its mp4 URL. A clip runs up to the model’s longest listed duration (the longest takes a multi-beat 30s spot in ONE take with native audio), so never assume an 8–10s cap or stitch what fits one clip; durationSeconds must be one of the model’s durations in hermoso_capabilities. NAME A MODEL in `model` to get it: an unnamed render uses a narrower auto-pool. 1–3 min. refImage anchors the first frame; ttsScript adds a voiceover. AUDIO IS NOT FREE BY DEFAULT: a clip with no audio of its own gets a music bed composed and CHARGED on top (see musicMood and audio), which can cost as much as a cheap draft clip. refVideo (a clip URL) EDITS that clip instead, keeping its canvas and length. RAW MODEL ACCESS: by default small guards are added (label safety with no reference image, a negative prompt where the model takes one, reference lines) and hex colours become names; raw:true dispatches your prompt to the model BYTE-IDENTICAL — no rewriting, no appended guidance, no negative prompt, no brand references attached on your behalf. Credits, the durable delivery of the finished asset and the per-model validation are unchanged. Spends credits (blocked on the Starter plan).
| Parameter | Type | Description |
|---|
dryRun | boolean | true = render NOTHING and return the credits this exact clip would hold (an estimate; the final charge is its actual cost). Free. Call this to price a clip before running it: without it the call renders and bills. |
prompt | string | the video prompt / shot description (for a refVideo edit, this is the transformation instruction); optional with `shots` |
raw | boolean | Send the prompt to the model exactly as written, without the wording Hermoso usually adds (packaging and label guidance, reference lines, colour names for hex codes, quality hints). Use it when you want the model's own interpretation rather than Hermoso's render craft. Two vendor-required fixes still apply: extra @ImageN tokens are dropped and an over-long prompt is trimmed at a sentence (on Veo it is refused with the length and the cap instead). Billing, durable delivery and per-model validation are unchanged. |
refImage | string | local path or URL to anchor the first frame. Using a real person’s face, likeness or voice confirms you are them or have their consent, take full, unlimited responsibility for its use and will cover any claim against Hermoso (hermoso.ai/terms). Paid plan only; recorded. |
speak | string | A PERSON SAYING THESE EXACT WORDS TO CAMERA — the default for any "make my photo talk" / spokesperson / talk-to-camera ask. Pass with `creator` or a portrait as `refImage`: the video model films them saying it in their own voice, matched to who they are, and the length follows the words (leave durationSeconds out). `prompt` is then the staging (e.g. "natural", "walking in a park"). Real footage, not an animated photo; generate_avatar is the animated-photo look, only when asked for by name |
creator | string | STAR A SAVED CREATOR in this clip — their id from list_creators, or the name you know them by, or a PRESET AI creator from list_creators presets (exact name or id; free, no generation). Their saved portrait rides first among the references as the on-camera person, with their saved consent, exactly as render_ad casts them; a real person saved from a photo keeps their real face on camera. An unknown name is refused by name, nothing charged. |
angles | boolean | OPTIONAL, OFF BY DEFAULT: with `creator`, also send the extra views that creator already has saved (their pose plates, up to 2) beside their portrait. A test showed no visible improvement over the portrait alone, and each extra view adds about 25 s before the render starts, so leave it off unless asked. Views are skipped when the face library is busy, and the render always goes ahead on the portrait. |
refImages | string[] | SEVERAL reference images (paths or URLs: a person, products, a place) that must all appear. A model uses up to its `refs.max` in hermoso_capabilities (one-image models take the first); with `refs.promptAddressed`, name them Image 1, Image 2… in order. minimax-h3-max-ref takes 9 and keeps each as a reference, not a first frame. |
refVideo | string | URL of an existing video to EDIT rather than generate from scratch — the clip is transformed per your prompt, keeping the SOURCE clip’s aspect ratio and, on models hermoso_capabilities marks `sourceLength`, its LENGTH (their `durations` are the per-second price ladder; a durationSeconds sent is reported as unused). Trim the source to change the length. Omit `model` for the default editor, or name a model whose videoEdit is true in hermoso_capabilities (a named model that cannot edit is refused, nothing charged); refImage rides along as the look of what the edit adds. With extend:true this is instead the clip to EXTEND. Omit to generate a fresh clip. |
endImage | string | local path or URL of the LAST frame: the clip travels from refImage (required with it) to this image. Only models with endFrame true in hermoso_capabilities take it; any other named model is refused by name, nothing charged. |
loop | boolean | true = a seamless loop whose last frame flows back into its first. Only models with loop true in hermoso_capabilities; needs refImage and cannot be combined with endImage. |
shots | object[] | MULTI-SHOT: one clip cut into these shots, in order; the seconds add up to a length the model renders. Replaces `prompt`. Only models with multiShot true in hermoso_capabilities; a shot prompt over that model’s shotPromptMaxChars (Kling 3.0: 512) is refused free, never cut. |
extend | boolean | true = EXTEND refVideo by durationSeconds (default 5) with what your prompt says happens next, as ONE clip. By default it CUTS to a NEW SHOT: new angle, same scene, room sound carried, no music at the cut. A named model (any i2v) renders it. |
extendMode | "cut" | "continue" | with extend: 'continue' = the SAME take past its last frame, only when asked seamless (models with extend in hermoso_capabilities). |
interactionId | string | with extend:true on an Omni model: the interactionId returned by an earlier render on that model — continues it from its own stored context instead of re-uploading refVideo. |
durationSeconds | number | length of THIS ONE clip in seconds: one of the CHOSEN model’s listed durations in hermoso_capabilities (they differ per model, 4–8s on the short ones up to 30s). One continuous generation, so a longer ask than the model’s longest clip is REFUSED, nothing charged (never quietly truncated). Past ~15s NAME a long-clip model in `model`. For a longer spot use plan_ad with durationSeconds then render_ad, which stitches acts (on a 15s model, 40s = 15+15+10). |
aspectRatio | string | default '9:16' |
model | string | video model id from hermoso_capabilities; a named model is never swapped without asking. Omit to let the router pick; its default per job (jobEngines in hermoso_capabilities, from watched side-by-side tests) is seedance-2.5 for product, lifestyle, a person talking to camera and 30s single takes (cheaper engines broke the product there). A model the user picks is kept; never switch it |
faceRoute | "face_lane" | 'face_lane' records the user's statement "I own the rights to this face" for the real person in their reference (paid plans; the likeness terms apply). Set it only when the user picked that option after a render said it could not use that face, and send the same request again; it then renders through Hermoso's face library at the normal price. Never set it on your own. The other options are a different `model` or one of the user's saved `creator`s. |
resolution | "480p" | "720p" | "1080p" | "4k" | Omit = the default tier, hermoso_capabilities defaultResolution (720p), the tier its `credits` prices are for. 1080p is ~2.25x, 4k more, 480p less: quote creditsByRes and pass the tier you quoted. A tier a model's `resolutions` lacks renders at its best one. |
cameraMove | "orbit" | "orbit_left" | "orbit_half" | "orbit_full" | "rise" | "crane_up" | "push_in" | "pull_back" | "reveal" | A named camera move around the still in refImage (orbit = a quarter turn, the default; orbit_half / orbit_full = a half turn / a turntable). Only minimax-h3-max-camera renders one: with model omitted it is picked; any other named model is refused, nothing charged. Needs refImage. |
cameraTrajectory | object[] | Your own ordered camera path, 2 to 12 keyframes, for the camera-controls model only (same rule as cameraMove; overrides it). The first pose is held until its time and the last pose is held to the end. A value outside these bounds is refused by name, nothing charged. |
ttsScript | string | voiceover script to speak |
ttsVoice | string | voice name, e.g. Rachel / George |
musicModel | string | compose the bed on minimax-music-3 or lyria-3.5, skipping the free library |
musicMood | string | the mood of the music bed (upbeat / calm / warm / epic / tense / playful / elegant / hype / chill / dramatic; default warm). It does not decide WHETHER there is one: a clip with no audio track (a "silent" model in hermoso_capabilities, or one that came back mute) gets a bed composed and CHARGED automatically at explainerMusicCredits. audio:false = silent, no bed, no charge. |
audio | boolean | default true. false = render SILENT: no native model audio, no music bed, and no bed charge held or billed. This is the ONLY way to decline the automatic bed (see musicMood) — leave it alone for anything that should have sound, and do not combine it with ttsScript. |
generate_avatar#
Generate talking avatar
ANIMATE A PHOTO so it talks: the presenter in `image` says `script` word for word, a separate voice lip-synced onto the still. Use it ONLY when the user asks for an animated photo / talking photo / lip-sync look by name; for any other talk-to-camera or spokesperson ask use generate_video with `speak` (the person filmed saying it, which reads as real footage). About 1-3 min, holds the pose steady, 480p/720p. The per-second credit price is in hermoso_capabilities (avatarEngines); dryRun:true returns this exact job's hold without rendering. Blocks until done where the host allows, else returns a job id to poll with get_job. Requires canAvatar. Spends credits; a refusal before rendering costs nothing.
| Parameter | Type | Description |
|---|
imagerequired | string | local path or URL of the presenter portrait. Using a real person’s face, likeness or voice confirms you are them or have their consent, take full, unlimited responsibility for its use and will cover any claim against Hermoso (hermoso.ai/terms). Paid plan only; recorded. |
scriptrequired | string | the words the avatar speaks |
voice | string | voice name (Aria / Sarah / George / Adam). Leave it out and the voice matches the person in `image`; if nobody can be read, the call is refused free asking for one |
engine | string | leave out for the standard engine; only an engine listed in hermoso_capabilities avatarEngines is accepted |
resolution | string | '720p' (default) or '480p' |
prompt | string | motion direction, only for an engine other than standard that hermoso_capabilities lists |
seed | integer | fixed seed, only for an engine other than standard |
acceptQueue | boolean | only for an engine hermoso_capabilities marks oneAtATime: wait in line |
dryRun | boolean | return the credits this exact job would hold, without rendering |
stitch_video#
Stitch multi-scene video
Render a multi-scene STITCHED video (≥2 scenes) — ONLY for spots LONGER than ONE clip of the chosen model. A multi-beat ad that FITS one clip renders better and cheaper as ONE single-pass generate_video/render_ad (a single generation carries the whole hook->demo->payoff arc) — never stitch those. What fits is the model’s own maximum from hermoso_capabilities, not a fixed number: 15s on most models, 30s on the longest-clip one, so a 30s spot need not be stitched at all if you name that model. Blocks until done. Spends credits.
| Parameter | Type | Description |
|---|
scenesrequired | object[] | array of scene objects (visual + optional voiceover/seconds) |
aspectRatio | string | output aspect ratio, e.g. 9:16 (default) / 1:1 / 16:9 |
voiceover | string | full voiceover script spoken across the scenes |
voice | string | voiceover voice name, e.g. Rachel / George |
resolution | string | 720p (default), 1080p for full detail, or 480p for a cheaper draft |
model | string | video model id from hermoso_capabilities — omit to let the router pick |
durationSeconds | number | total spot length in seconds (defaults to the sum of the scenes’ seconds) |
get_job#
Get render job read-only
Poll a render job by id. Returns status (queued|running|done|error), progress, and on done the served media URL. Renders take 1–3 minutes: keep calling this until done/error without asking the user — several calls is normal, not a stall. An id that does not exist on this account answers status "not_found" — that is FINAL: stop polling it, and do not re-fire the render (that double-charges).
| Parameter | Type | Description |
|---|
idrequired | string | the job id: starts with job_, from a render tool's jobId or from list_jobs (generate_voice and generate_sfx return their file directly and have no job) |
post-production & analysis
analyze_video#
Analyze video
A video ad's structure: verbatim transcript (voiceover + on-screen text), beat list, duration and sampled frame times; study a reference before remixing it. ~A transcription call.
| Parameter | Type | Description |
|---|
urlrequired | string | the video URL (a served /generated/ path or a public http(s) video) |
frames | boolean | also return the frames as images |
words | object | true | 'only': each spoken word's start/end |
anchors | object[] | {afterWord|beforeWord|atWord, occurrence?, offset?} -> s |
repurpose_transcript#
Repurpose a video transcript
Turn a VIDEO into WRITTEN pieces: a summary, YouTube chapters (first at 0:00, at least 3, each 10s+), chapter summaries, an X thread (every post under 280 characters), a blog post, timestamped verbatim quotes, or any piece in your own words (pass the words as a format). The video: a YouTube link (read from its captions), a video file URL, a Library id, an upload_file URL or a social post link (read by watching it); or the text itself, when you already have it from analyze_video (which is the tool that just reads a video back). Several formats share ONE read. Priced by the video's length before anything is spent: without confirm it returns the exact credits and spends nothing; confirm:true writes and charges exactly that. Only the paid minutes are read. Every piece is written only from what the video says. Built-in skills youtube_script and retention_skeleton (get_skill) write long-form scripts.
| Parameter | Type | Description |
|---|
video | string | a YouTube link, a video file URL, a Library id (L0…), an upload_file URL or a social post link |
transcript | string | the transcript text, when you already have it; then nothing is read |
formats | string[] | summary, chapters, chapter_summaries, thread, blog, quotes, or any piece in your own words; default summary |
instructions | string | your direction for every piece: audience, tone, length, a call to action |
language | string | the language to write in, when not English |
seconds | number | the video length in seconds, when you know it: it prices exactly that, and anything past it is not read |
read | "auto" | "watch" | 'watch' reads a YouTube video by watching it rather than from its captions (one with no captions) |
model | string | a Claude writing-model id from hermoso_capabilities; omit for the default |
includeTranscript | boolean | also return the transcript that was read |
confirm | boolean | true only after the user agreed to the quoted price |
find_sound#
Find a sound
A sound for an edit by name ('the FAAAA sound'), by the moment ('bad news reaction') or by link (TikTok sound, meme-sound page, post, audio file): a durable mp3 and where it starts and lands. Named/described sounds come from what TikTok uses now; pick takes another candidate. A sound that does not exist yet is generate_sfx.
| Parameter | Type | Description |
|---|
query | string | sound by name, moment or meaning, e.g. 'bad news reaction' |
url | string | link to a TikTok sound, a post, a meme-sound page or an audio file |
pick | number | candidate number from the previous list to take instead of the first |
make_insert#
Make an insert clip
A reaction picture (image, or video from videoStart) with its sound, cut to when the sound lands (or seconds): a 1080x1920 clip for post_edit join.
| Parameter | Type | Description |
|---|
image | string | still picture URL; use this or video |
video | string | video URL to take the picture from, starting at videoStart |
videoStart | number | seconds into the video where the insert starts |
soundrequired | string | sound URL (find_sound returns one), or a video whose own audio is used |
soundStart | number | seconds into the sound where the insert's sound starts |
soundEnd | number | seconds into the sound where it ends |
seconds | number | fixed insert length, 0.2 to 6 seconds, instead of when the sound lands |
score_ad#
Score ad
Virality/performance prediction for a finished ad (image or video URL): overall score, per-dimension breakdown (scroll-stop, hook, clarity, brand/product, CTA, retention, goal fit), strengths, and the single biggest fix. Use BEFORE spending on distribution, or to rank variants.
| Parameter | Type | Description |
|---|
urlrequired | string | the ad asset URL (a /generated/ path or public URL) |
kind | "image" | "video" | 'image' (default) or 'video' |
intent | string | what the ad is trying to achieve, for goal-fit scoring |
reframe_video#
Reframe video
Reframe a video to a different aspect ratio (e.g. 16:9 master -> 9:16 vertical): the whole original frame is kept and the new canvas around it is generated, with the sound and timing unchanged. Clips up to 300 seconds. Paid render; returns the served URL of the reframed video. Every placement at once (a free blur-pad by default): repurpose_video. A presenter on any video: add_presenter.
| Parameter | Type | Description |
|---|
videorequired | string | the source video URL |
aspectRatiorequired | "9:16" | "1:1" | "16:9" | "4:3" | "3:4" | "21:9" | "9:21" | the target aspect ratio |
repurpose_video#
Repurpose a video for every placement
ONE video in, EVERY placement out, in one job, as a named file list (<name>_<placement>_<WxH>[_<lang>].mp4) with a manifest. Placements: 'everywhere' (default: 9:16, 4:5, 1:1, 16:9), any W:H, a pixel size (1200x628) or a platform word (tiktok, reels, stories, feed, square, youtube, linkedin, pinterest). Each is reframed by a BLUR-PAD by default (the whole frame over a blurred copy of itself; free, no AI), reframe 'crop' (fill, edges cut; free) or 'ai' (the new canvas generated around the frame; paid, for a canvas the engine makes, else padded and said). A placement may be {placement, reframe} to mix. Optional captions (word-timed, ~4 words a cue, placed for each canvas) and languages (a lip-synced dub per language; every placement of each). A pack of pads and crops only is billed 0. dryRun:true = the exact price (the sum of every leg's own price), which is what it charges. For ONE canvas use post_edit op pad.
| Parameter | Type | Description |
|---|
videorequired | string | the video: an https / upload_file URL, a Library id (L0…), or a local path on the CLI |
placements | string | object[] | default ['everywhere']; a canvas, a WxH size, a platform word, or {placement, reframe} |
reframe | "pad" | "crop" | "ai" | default 'pad' (free); 'ai' is paid and only when the user asks |
pad | object | the pad's look: fill 'blur' (default) or a #rrggbb colour, blur 0-1, dim 0-0.6, position top/center/bottom or 0-1 |
captions | boolean | string | object | true = word-timed captions on every file (only when the user asks); a textStyle preset name or object sets the look |
wordsPerCue | integer | captions: 1-8 words a cue (default 4) |
languages | string[] | dub into these languages (paid), e.g. ['Spanish','de']; the original is kept too |
name | string | the asset name the files are named after |
dryRun | boolean | price only: nothing made, nothing charged |
repurpose_image#
Repurpose a static ad into variants × formats
ONE finished static ad in, VARIANTS × FORMATS out, in one job, as a named file list (<name>_<variant>_<format>_<WxH>.png) with a manifest. The ad's text is read ONCE as the source of truth; each variant's change is made ONCE on the master; every format is derived from that master; every output is text-checked line by line and any line it lost is named (never re-rendered). Variants: {headline}, {language}, {swap:[{from,to}]} (exact words: a price, an offer, a CTA) or {edit} (any change in words), each with an optional {name}; the original is always included. Formats: default 1:1, 4:5, 9:16, 16:9, or 'everywhere', any canvas or a platform word (snapped to the nearest canvas an image model makes). At most 24 renders. dryRun:true = the exact price, which is what it charges. One resize alone is resize_ad.
| Parameter | Type | Description |
|---|
imagerequired | string | the ad: an https / upload_file URL, a Library id (L0…), or a local path on the CLI |
formats | string[] | default ['1:1','4:5','9:16','16:9'] |
variants | string | object[] | the versions besides the original; a bare string is an edit in words |
name | string | the asset name the files are named after |
fixLabel | boolean | false = no product-label check (default on when the ad shows the brand's saved product) |
dryRun | boolean | price only: nothing made, nothing charged |
add_presenter#
Add a presenter to any video
Put a PRESENTER on ANY video, only when the user asks for one: their pick of person (`creator`: a saved or preset creator from list_creators; or `image`: a photo they gave; never invent one), filmed on a green screen saying the words, cut out and laid over the video in a bottom corner (default), a round badge, or split screen, lip-synced, block by block across the whole video (about 10 s and about 25 spoken words a block). The words are `script` (verbatim; refused free if it cannot fit) or, without one, written to fit from what the video says and shows (`brief` steers them). The video's own sound stays under the presenter unless baseAudio 'off'; the video without the presenter is kept. A face the video model refuses STOPS it with nothing charged: offer another creator, another photo, or the video as it is. dryRun:true = the exact price, which is what it charges. For a finished make_explainer film, make_explainer with fromFilm.
| Parameter | Type | Description |
|---|
videorequired | string | the video: an https / upload_file URL, a Library id (L0…), or a local path on the CLI; up to 2 minutes |
creator | string | the presenter: a saved or preset creator, by name or id |
image | string | or a photo of the presenter (a real person's face follows the real-face rules) |
script | string | the exact words to say, used verbatim and split at sentence ends |
brief | string | without a script: what they should talk about |
look | "corner" | "badge" | "split" | |
position | string | 'br' (default), 'bl', 'tr', 'tl' |
scale | number | 0.2-0.8 of the frame |
voice | string | a voice name, only when asked (default: their own voice) |
baseAudio | "under" | "off" | the video's own sound: 'under' the presenter (default) or 'off' |
captions | boolean | subtitles of what they say; only when asked |
dryRun | boolean | price only: nothing made, nothing charged |
insert_scene#
Insert a new scene into a video
INSERT a newly generated scene into a clip you already have: the video plays up to startTime, the new scene (5 to 13 seconds) plays, then the original picks up again at resumeTime. Use for a product close-up, a reaction, a reveal or a missing beat in the middle of an ad without re-rendering the rest. resumeTime = startTime keeps every second of the original; a later resumeTime also cuts the footage in between. Describe the scene in prompt and/or attach up to 4 reference pictures (refImages) or 1 reference clip (refVideos). Clips up to 60 seconds; both times between 1.625 and 60 seconds. Paid render (billed per second of NEW scene); returns the whole video's URL.
| Parameter | Type | Description |
|---|
videorequired | string | the source video URL (a render, job result or list_library item) |
startTimerequired | number | seconds into the clip where the new scene starts (1.625-60) |
resumeTimerequired | number | seconds into the ORIGINAL clip where it picks up again after the new scene (2.625-60, at or after startTime) |
prompt | string | what happens in the new scene: the action, the subject, the camera |
seconds | number | length of the new scene, 5-13 seconds (default 5) |
refImages | string[] | up to 4 picture URLs of what should appear (the product, a person, a place) |
refVideos | string[] | up to 1 clip URL whose look or motion the scene follows |
resolution | "480p" | "720p" | default 720p (rendered at 768p); '480p' is cheaper |
upscale_video#
Upscale video
Upscale a video to higher resolution (2x) for final delivery. Paid render; returns the served URL. A 480p Seedance 2.5 draft: finish_draft (same take, native 1080p). Three engines: the default ('standard') is the safe precision upscaler; engine:'flux' is the FLUX 3 video upscaler (1080p/2K/4K) with an optional mode:'creative' detail-enhancement pass; engine:'detail' rebuilds fine detail such as hair, skin and fabric, the sharpest result for a hero shot and the most expensive. Pick 'flux' or 'detail' when the user asks for added detail rather than a faithful enlargement.
| Parameter | Type | Description |
|---|
videorequired | string | the source video URL |
engine | "standard" | "flux" | "detail" | default 'standard', the precision upscaler. 'flux' = the FLUX 3 video upscaler. 'detail' = rebuilds fine detail, costs the most |
mode | "precise" | "creative" | FLUX only — 'creative' turns on its detail-enhancement pass; default precise |
finish_draft#
Finish a draft in 1080p
FINISH a 480p Seedance 2.5 DRAFT in 1080p: the model regenerates THAT take (same scene, shots, motion, sound) at full resolution. Every 480p Seedance 2.5 render (generate_video / render_ad at resolution 480p) is a draft, finishable for 7 days; its result carries `draft` {id, expiresAt, finishCredits}. Pass that id, or the draft video URL. It is the full-resolution route for a draft (upscale_video is for a video that is not a draft); priced like a 1080p render of its length. Paid: call with dryRun first, state the credits, run only when the user agrees. Captions, end card or music added after the draft are not re-applied. Not a draft or expired: a plain refusal; use upscale_video or a fresh 1080p render.
| Parameter | Type | Description |
|---|
draft | string | the draft id from the render result (draft.id) |
video | string | or: the URL of the 480p draft video |
dryRun | boolean | true = return the estimated credits and render nothing |
restyle_video#
Restyle a video
RESTYLE a clip into a new LOOK: every frame redrawn, shots, motion, camera, framing, timing and sound kept. Looks: `Restyle looks` in hermoso_capabilities (claymation, knitted yarn, cel-shaded CG anime…), your own words, or a look BUILT FROM YOUR IMAGES (styleImages); characters draws your own characters in. engine auto (default) picks by what is in the clip: a real-looking person -> kling (Kling 4.0 Edit, 3-15s); none -> wan (Wan 3.0, recommended, ≤15s) else seedance (Seedance 2.5, 4-30s); wan-prime = Wan 3.0 Prime by name (costs more). Paid; dryRun quotes it. One change only: edit_video.
| Parameter | Type | Description |
|---|
videorequired | string | the source video URL (a render, job result or list_library) |
style | string | a look id from hermoso_capabilities (e.g. claymation, knitted-yarn, cel-shaded-anime-cg) |
describe | string | a look in the user’s own words, when no preset fits, or extra detail on top of a preset |
styleImages | string[] | pictures that ARE the look (their style, never their subject) |
characters | string[] | characters to draw the people as. Using a real person’s face, likeness or voice confirms you are them or have their consent, take full, unlimited responsibility for its use and will cover any claim against Hermoso (hermoso.ai/terms). Paid plan only; recorded. |
engine | "auto" | "seedance" | "wan" | "wan-prime" | "kling" | default auto |
resolution | "480p" | "720p" | "1080p" | Seedance and Wan; default 1080p |
faceRoute | "face_lane" | 'face_lane' = the user's "I own the rights to this face" for a real person in the source clip (paid plans). Only on the user's say-so, never on your own. |
edit_video#
Edit a video clip
SWAP AN OBJECT IN A VIDEO ('replace the cup with our can' + the product photo as elements) or EDIT an existing clip from a plain instruction (video-to-video): the motion, timing, framing and cut stay, the named thing changes. 'change only the mug to red', 'make it nighttime', 'restyle it as claymation'. Your words are wrapped so the model keeps everything else identical, changes only what you named and repeats that lock; lighting is kept unless the change needs new light (set lighting to force either); literal:true sends your words as written. One change per call holds best. previewFirstFrame:true edits ONE still first (one image edit; previewAt picks the second) and quotes the clip; nothing else runs until you call again, ideally with previewStill. The reply scores how well the shot held outside the change (free) and flags an edit that touched more than asked. NOT for cuts/trims/end cards (post_edit), a new video (generate_video / render_ad), translating what is SPOKEN (dub_video) or a saved creator's face (recast_motion). Translating or rewriting the on-screen words of a video laid out from a design (a template ad, a custom design) is textChanges with every line at once: one re-make of the design, about 2 credits. Best on 3-15s clips.
| Parameter | Type | Description |
|---|
videorequired | string | the source video URL (a render, job result or list_library) |
instructionrequired | string | the change, in the user’s own words |
keepAudio | boolean | default true: keep the source audio; false = silent |
lighting | "auto" | "preserve" | "relight" | default auto: keep the source light unless the change needs new light (night, a lamp, fire). 'preserve' or 'relight' forces it |
reference | string | OPTIONAL image URL that anchors the MATERIAL of what changes (a fabric, a finish, a colour swatch, the real product). Only its surface is used, never its framing or light |
literal | boolean | true = send the instruction exactly as written, with no preserve/lock wrapper |
previewFirstFrame | boolean | true = edit ONE still of the first frame first and quote the clip; the paid clip does not run |
previewStill | string | the still a previewFirstFrame call returned; the clip then matches the changed thing to it |
previewAt | number | second to preview (default 0); resend with previewStill |
elements | object[] | OPTIONAL identity/product grounding (≤4): a creator portrait or the real product photo, so the edit restores the REAL thing. Describe each one in the instruction |
interactionId | string | OPTIONAL: the interactionId an earlier Gemini Omni render or edit returned; the edit continues that clip on the same Omni model. If it cannot run, the video editor edits it and the reply says so. |
engine | "auto" | "seedance" | "kling" | default auto: Seedance 2.5 Edit without a real-looking person, else Kling 4.0 Edit |
faceRoute | "face_lane" | 'face_lane' = the user's "I own the rights to this face" for a real person in the source clip (paid plans). Only on the user's say-so, never on your own. |
textChanges | object[] | EVERY change of on-screen words at once ([{from, to}], e.g. each line and its translation). A video laid out from a design is made again with all of them in ONE render, about 2 credits, never a video edit |
multiply_ad#
Multiply an ad
MULTIPLY a winning video ad into N variants: each gets a NEW character, outfit, location and/or objects while the cut, the camera motion, the pacing and the ORIGINAL AUDIO stay exactly as they were (that is what made the ad work), and any burned-in captions are removed. Pass the source video URL (a previous render, a job result, list_library, or the top performer from post_performance / meta_insights). HOW: the source video itself DRIVES each variant (motion transfer from one image-edited opening frame), so every variant comes back the SAME LENGTH as the source with the same cut, the same performance and the original audio — only the person, outfit, set and props change. Sources up to 30 seconds work as they are; longer ones are refused for free with the way out (trim it first: post_edit with ops [{op:'trim', start:0, end:30}] — clip_video is the AI highlight clipper, not a trim). Returns the plan and ONE JOB PER VARIANT — call get_job on each until it reports done; do not describe a variant before its URL arrives. COST: quoteOnly:true returns the exact credits free: state that first. A paid planning read (planCredits) runs next, then each variant bills perVariantCredits. dryRun:true pays for that read; pass its `plan` back to render without paying again. Your own pictures: images takes up to 9 of the user's product, people, clothes or places, and change names them @Image1, @Image2 in order ('she holds the bottle in @Image1'); the saved brand's product photo is read as a reference to its real look (useBrand:false leaves it out). A TikTok, Reel, Facebook, X or YouTube post link works as the source: one paid lookup reads it into a file. quality: 1080p (default) or 720p; quoteOnly prices both. Regions: pass regions:['Berlin','Tokyo'] to restyle variants per market; translation is a separate, explicit step — dub_video on a finished variant. `change` is what should change, in the user's own words ('older women', 'winter streets', 'swap the mug for our bottle'): every variant applies it and the variants still differ around it; a part of it about the voice, words, language, music, length or captions cannot change here, and the reply says so and names the tool that can.
| Parameter | Type | Description |
|---|
videorequired | string | the source video: a file URL, or a TikTok, Reel, Facebook, X or YouTube post link |
images | string | object[] | up to 9 pictures to put in the variants, in the order @Image1, @Image2 name them: URLs or local paths |
quality | "1080p" | "720p" | 1080p is the default; 720p costs less, and hands holding a product are less reliable at 720p |
useBrand | boolean | false = send no brand product photo (for a video that is not this workspace brand) |
count | number | how many variants, 1-12 (default 6) |
change | string | what should change, in the user's own words, e.g. 'older women, winter streets'; every variant applies it (omit to let the variants vary freely) |
axes | string[] | what to vary: character, outfit, location, objects (default all four), or your own, e.g. "season" |
notes | string | anything the variants must respect, e.g. "keep it women 25-40", "no gyms" |
regions | string[] | markets to restyle for, one or more variants each, e.g. ["Berlin","Tokyo","São Paulo"] — visuals only; audio is never translated here |
quoteOnly | boolean | true = the exact credits, free; nothing runs |
dryRun | boolean | true = the paid plan and the price, no render |
plan | object | the `plan` a dryRun returned, rendered without planning again |
hook_variants#
New opening hooks for a video
HOOK MULTIPLIER: give ONE finished video ad N NEW OPENING HOOKS, N complete versions to A/B test. A planned hook replaces the first ~1.5-4 s (ends at the source's first cut there, else 3 s; hookSeconds overrides) with a new silent shot on a DIFFERENT named mechanic (list_hooks); the rest of the footage and the WHOLE original soundtrack stay, so every version keeps the source's length, and nobody in the hook talks or shows text. hooks[] adds your own openings: {url} a FOUND viral hook (post link or file) joined in front with the approved bridge (cut before its payoff, its own payoff sound carried across; post_edit price), {prompt} an opening described in words, {mechanic} a named one; with hooks and no count only those are made. To make the found hook's subject your product or creator first: recast_hook. Pass the video's FILE URL (a render, job result, list_library or upload_file). 1-5 versions, default 3. Refused free before billing: a source over 120 s, too short for a 1.5 s hook plus 2 s after it, unreadable, or a social post as the SOURCE (clone_video remakes someone else's ad). COST: quoteOnly:true returns the exact credits free: state that first. A paid planning read (planCredits) runs next, then each planned version bills like fix_beat for the hook's seconds. dryRun:true pays for that read; pass its `plan` back to render exactly those. Returns ONE JOB PER VERSION; call get_job on each until done, never describe a version before its URL arrives. Hooks that show the product use the brand's product photo (productImage overrides; useBrand:false sends none).
| Parameter | Type | Description |
|---|
videorequired | string | the finished video to give new hooks: its served file URL |
count | number | how many hook versions, 1-5 (default 3) |
notes | string | anything the hooks must respect, e.g. "keep it calm", "show the product in every hook" |
hookSeconds | number | where the CURRENT hook ends, in seconds (1.5-4). Omit to use the first shot cut. |
resolution | "480p" | "720p" | "1080p" | render tier for the new opening. Defaults to the source’s OWN tier so the hook matches the rest of the ad; a lower tier costs a lot less and is scaled into the source’s canvas (visibly softer for the first seconds). dryRun quotes whichever you pick. |
productImage | string | product photo URL used as a reference in hooks that show the product (defaults to the workspace brand’s first product photo) |
useBrand | boolean | false = send no brand name or product photo (for a video that is not this workspace brand’s) |
plan | object | the `plan` object a previous dryRun returned, to render exactly those hooks without planning again |
quoteOnly | boolean | true = the exact credits, free; nothing runs |
dryRun | boolean | true = the paid plan and the price, no render |
hooks | object[] | your own openings, one version each |
dub_video#
Dub video
Localize a finished video into another language WITHOUT re-rendering it: each spoken line is said where it was said, in a native voice, lip-synced, background kept. Pass the video and the language; the script is read off the source (`script` only overrides it). Paid by length; dryRun quotes. Returns the localized video URL.
| Parameter | Type | Description |
|---|
videorequired | string | the source video URL |
languagerequired | string | target language, e.g. 'Spanish', 'de', 'French (Canada)' |
script | string | OPTIONAL override for the original spoken words. Leave this out — the source video is transcribed automatically. Only pass it when you already know the exact script and the auto-transcript got it wrong. |
voice | string | optional, e.g. 'Aria' (woman) or 'George' (man): a native voice of that sex speaks. Default: the source speaker's sex. |
dryRun | boolean | quote only |
change_voice#
Change narrator voice
Swap the narration of a finished video into a different voice — keeps the performance, lip-sync, and background sound. Use when the user likes the video but wants a different narrator voice; use dub_video only for language translation. Paid; returns the served URL.
| Parameter | Type | Description |
|---|
videorequired | string | the source video URL |
voice | string | target narrator voice preset name, e.g. 'Aria', 'George', 'Rachel', 'Sarah', 'Brian', 'Charlotte' (defaults to a warm female read). A saved VOICE CLONE of the user's own voice counts as a preset here — name it the way it is saved on their cast |
recast_motion#
Recast motion
Copy the motion of any video (motion transfer): re-perform a clip's motion, camera and timing with YOUR character, product, clothes or place; sound kept. image (+ images, @Image1, @Image2… in prompt) = who and what. engine auto (default): a person clip + ONE photo of a person (saved, real or AI), 4-30s -> seedance (Seedance 2.5 through our face library, 720p: the clip's scene, beats and sound kept, the WHOLE person swapped) when the clip is one of our renders or faceRoute is set; otherwise wan (Wan 3.0, scene kept, 3-15s, 720p), past 15s kling-edit (Kling 4.0 Edit, 3-30s, 1080p by asking); several photos (one per person) -> h3 (H3 Max Recast, ≤4 photos, 5-30s); no person in the clip -> seedance. By name: kling-edit; wan = Wan 3.0 (≤15s, keeps the set); wan-prime; h3; kling = Kling Motion Control (ONE picture, its background becomes the set). voice/language: the new performer gets a new voice (same timing) or speaks another language (lip-synced), in the same job and price. Billed per output second, ~5 min per 5s; dryRun quotes.
| Parameter | Type | Description |
|---|
image | string | who performs it: the actor/character image URL (@Image1). Required on kling. No one yet: generate_image a portrait of an AI person from words (no reference photo) and pass its url, or a saved / preset creator’s portrait (list_creators). Using a real person’s face, likeness or voice confirms you are them or have their consent, take full, unlimited responsibility for its use and will cover any claim against Hermoso (hermoso.ai/terms). Paid plan only; recorded. |
images | string[] | seedance/wan: more pictures, @Image2…: a character, product, outfit or place |
videorequired | string | the reference video whose motion to re-perform |
prompt | string | optional, e.g. 'same moves, new location: Tokyo at night' |
engine | "auto" | "kling-edit" | "h3" | "seedance" | "wan" | "wan-prime" | "kling" | default auto |
resolution | "480p" | "720p" | "1080p" | a person swap defaults to 720p (seedance or kling-edit); otherwise seedance and wan default 1080p; h3 720p or 1080p, default the clip’s own |
orientation | "video" | "image" | kling only: which aspect to keep: the video's (default) or the image's |
faceRoute | "face_lane" | 'face_lane' = the user's "I own the rights to this face" for a real person in the source clip (paid plans). Only on the user's say-so, never on your own. |
dryRun | boolean | return the credits this exact job would hold and the engine auto picks, without rendering |
voice | string | a NEW voice for the new performer: 'match' (a stock voice that fits them), 'female'/'male', or Aria, Sarah, Charlotte, George, Brian, Charlie. Omit = the clip's own sound. Never the original speaker's or a cloned voice |
language | string | the new voice speaks this language (e.g. 'Spanish'), lip-synced to the new words; voice defaults to 'match' |
tier | "pro" | "standard" | kling only: 'pro' (default): 1080p and real hand-object interaction. 'standard': about 25% fewer credits and faster, but 720p, and it tends to mime a held object with empty hands. hermoso_capabilities lists the exact credits for both |
recast_hook#
Recast a viral hook with your subject
RECAST A VIRAL HOOK with the brand's own subject (the egg rolling off the table becomes your product; your host does the viral move), then join it into your clip. voice/language: a new voice, or language lip-synced, for one person swapped in. hook: a public post link (TikTok, Reel, Facebook, X, YouTube; one lookup) or a video file. Subject: creator (saved name or id), image (a product or person; a real person's photo records consent), or neither for the brand's first product photo. A DUO OR GROUP (2-4 people): subjects [{creator or image, position: 'left'|'right'|'center' or your own words, refs?, outfit?}], each bound to its place in the frame, keeping that performer's movement and timing on the original sound. LOCATION AND OUTFITS, same pass: location (a place photo or words) moves the scene; outfit (a photo or words) re-dresses the subject, subjects[].outfit each person; with no subject named nobody is swapped and only those change (useBrand:true also swaps in the brand product). Pictures are references, 4 at most; more go in words. Person for person: Seedance 2.5 (720p) if the hook is our render or faceRoute is set, else Wan 3.0 (≤15s; Kling 4.0 Edit past). FULL LENGTH: past its one pass (30 s) the window is recast in passes, each continuing from the previous one's frame and crossfaded across the cut, under the original sound: one video up to 60 s, quoted as passes plus join; the reply names the cut. mode 'auto' is always 'swap' (a region edit: camera, set, light, timing, text and sound kept; a multi-shot hook goes shot by shot); 'motion' only if asked (your person moves in their own photo's setting). swap: your own words for what changes. start/end pick the window (3 s minimum; default: a group or a location/outfit change takes the whole clip, one subject the first 10 s). PAID, QUOTED FIRST: no confirm returns the plan and credits; confirm:true once the user okays it. Then get_job until done, and post_edit with videoUrl = the result and ops [{op:'join', clips:[{url: your clip}], bridge:{kind:'impact'}}].
| Parameter | Type | Description |
|---|
hookrequired | string | the viral hook: a post link or a video URL |
creator | string | a saved creator's name or id (list_creators). NONE SAVED: cast a preset by exact name (list_creators), or pass image instead: a portrait of an AI person that generate_image painted from words (no reference photo) swaps in on every plan, nothing to save. A described lookalike of the user is fine on every plan; a photo of anyone is a real face (paid plan) |
image | string | a picture of the subject instead: a product or a person. A person generate_image painted from words with no reference photo counts as an AI face on every plan |
subjects | object[] | a duo or group recast, 2-4 people, instead of creator/image |
location | string | move the scene: a photo URL of the place, or words ("a sunny beach at golden hour") |
outfit | string | what the subject (or, with no subject, the main person in the hook) wears instead: an outfit photo URL or words |
swap | string | what changes, in your own words |
mode | "auto" | "swap" | "motion" | auto (always a swap), swap (edit what you describe), or motion (move your person in their own photo's setting) |
start | number | window start in seconds of the hook; minimum window is 3 seconds |
end | number | window end in seconds of the hook |
prompt | string | extra direction for the render |
model | string | swap: omit for the default; a clip editor id (kling-4-edit, kling-o3-edit; hermoso_capabilities), or for one person swapped for another 'wan-3' (≤15 s) / 'minimax-h3-max-recast' |
faceRoute | "face_lane" | 'face_lane' = the user's "I own the rights to this face" for a real person in the source clip (paid plans). Only on the user's say-so, never on your own. |
resolution | "480p" | "720p" | "1080p" | swap: the output tier, on an editor that prices by one (kling-4-edit 720p or 1080p); default the hook's own pixels |
tier | "pro" | "standard" | motion: the motion-transfer tier (default pro) |
useBrand | boolean | false = no brand product photo; true with location/outfit and no subject = also swap in the brand product |
voice | string | one person swapped in: a NEW voice for them instead of the original speaker's: 'match' (fits them), 'female'/'male', or Aria, Sarah, Charlotte, George, Brian, Charlie. Omit = keep the clip's voice. Never a cloned voice |
language | string | the new voice speaks this language (e.g. 'Spanish'), mouth lip-synced to the new words; voice defaults to 'match' |
confirm | boolean | true = render it (after the user okayed the quote) |
face_check#
Check a picture or video for a face read-only
Before any paid render: does a picture or video contain a face, and which video models refuse it (they cannot take a real person's face; a render there fails after it starts) or were measured to take one, plus the model a face-bearing render is routed to. A local detector, no model call, 0 credits. It cannot tell a photo from a drawing, so a drawn face counts. Takes a picture or video URL, a Library item or a public post link. A file or Library item is free; a TikTok / Reel / Facebook / X post link is opened through one paid lookup (1 credit), refused when the account has no credits.
| Parameter | Type | Description |
|---|
urlrequired | string | the picture or video to check |
plan_variations#
Plan ad variations
Fan a brief into N DISTINCT ad angles (different hooks/mechanics/audiences), each with its own headline + visual brief — then render each with generate_image and rank with score_ad. LLM planning only; renders nothing itself. To plan AND render a batch of finished static ads for one or several products in one call (up to 20 per product), use make_static_ads.
| Parameter | Type | Description |
|---|
brand | string | object | brand name or profile object; OMIT to use the workspace’s saved brand |
productrequired | string | what to advertise |
count | integer | how many distinct variants (default 6) |
language | string | output language for the variant copy (e.g. Spanish) — default English |
make_static_ads#
Make static ads at scale
Make a BATCH of finished static image ads for one or several products in one call: each ad a genuinely different selling angle (offer, material or ingredient story, how it is used, a lifestyle moment, an objection, proof the brand really has) AND a different layout (editorial still life, poster headline, packshot on colour, in hand, flat lay, split compare, native phone photo and more; never one look repeated across a batch), with its headline, supporting line and CTA printed on the image and the product's real photo and the brand's real logo composited in. `products` names products from the brand's product catalog by id or name (list_products; add one from its page link with add_product; ['all'] takes every product with a photo; omit for the hero product). A product's price is printed only when it was read from its live page within the last hour: older rows are re-read first, and a page that cannot be read means no price on that ad. `count` is ads PER PRODUCT (1-20). `aspectRatios` any of 1:1, 4:5, 9:16 (each ad is composed natively once per ratio, so the ratios are different pictures with the same words; for one picture in several sizes render one ratio and use resize_ad). `brief` steers (a sale, a season, an audience) and is never turned into a price, discount or claim the brand does not state; `angles` names the angles to spread across; `layouts` (free words) replaces the layout set. ALWAYS PRICED FIRST: dryRun:true returns the plan and the quote; then pass that `plan` (and its `batchId`) back to render exactly it without planning again. Renders are QUEUED jobs, at most 12 per call: the rest comes back as `remaining`, to send again as `plan` once some finish. Read each job with get_job; never describe an ad before its URL arrives. For variants of ONE finished ad use headline_variants / resize_ad; to copy a competitor's static use clone_static.
| Parameter | Type | Description |
|---|
products | string[] | product ids or names from list_products, ['all'] for every product with a photo, or omit for the hero product |
count | integer | ads per product, 1-20 (default 4) |
aspectRatios | "1:1" | "4:5" | "9:16"[] | canvases; every ad is rendered once per ratio (default ['4:5']) |
brief | string | what to lean into: a sale the brand is really running, a season, an audience, a tone |
angles | string[] | the selling angles to spread across, e.g. ['price or offer', 'material story', 'how it is used', 'lifestyle moment']; omit and the planner picks a spread |
layouts | string[] | your own layout descriptions in words, used slot by slot instead of the built-in layout set |
language | string | language of the on-image copy (default English) |
model | string | image model id from hermoso_capabilities; omit for the default |
brandId | string | a profile id/name from list_brands; omit for the active profile (passing it pins it like use_brand) |
plan | object[] | the `plan` (or `remaining`) a previous call returned: render exactly those ads, no new planning |
batchId | string | the batchId a previous call returned, so the rest lands in the same batch |
dryRun | boolean | true = plan and quote only, nothing rendered |
logoPlacement | "auto" | "overlay" | "in_scene" | "none" | overlay (default) | in_scene (real file printed onto a blank surface) | none | auto |
make_listing_set#
Make a marketplace listing set
Make a marketplace LISTING SET for ONE product in one call (Amazon, Shopify, Etsy, any store page): the MAIN image on pure white (the product alone filling about 85% of the frame, no text, no props, no added logo), then the secondary images a listing carries — a lifestyle shot, a detail close-up with NO infographic, a scale shot that shows its true size, and the product in use — every one rendered from the product's real photo and held to one visual system (the same light, scale and palette). More shots on request: multi_angle, whats_in_box, back_of_pack, or any shot in your own words. The MAIN renders FIRST and every other image is drawn from it (each waits for it in the queue), so the set matches; pass an approved main as mainImage to redo the rest from it. aplus:true adds Amazon's 7 A+ modules (a 21:9 brand hero and brand promise, 3:2 modules 2-6), each also delivered at its Amazon module's exact pixels, with its text fields suggested only from the product's own data. Priced up front: dryRun:true returns the plan and the exact credits; the charge is that number. Each image is its own queued image job (poll with get_job); they land in the Library. For a batch of ADS use make_static_ads; for one product photo in a scene use plan_ad + generate_image.
| Parameter | Type | Description |
|---|
product | string | the product name or id from list_products: its catalog photo and its own facts are used |
image | string | the product photo when it is not in the catalog: an https or upload_file URL, a Library id (L0, L1…) or a local path on the CLI |
title | string | the product name, when it is not in the catalog |
description | string | what the product is, when it is not in the catalog |
inBox | string[] | what ships in the box (for a whats_in_box shot); nothing else is ever drawn in it |
shots | string[] | the images, in order: built-in main, lifestyle, detail, scale, in_use, multi_angle, whats_in_box, back_of_pack, or any shot in your own words. Default: main, lifestyle, detail, scale, in_use. main always comes first when asked |
aspectRatio | "1:1" | "4:5" | "3:4" | "4:3" | "16:9" | "9:16" | "2:3" | "3:2" | the canvas for the whole set; default 1:1 (the marketplaces' square) |
brief | string | the seller's direction for the whole set: a mood, a setting, an audience |
model | string | image model id from hermoso_capabilities; omit for the default |
brandId | string | a profile id/name from list_brands; omit for the active profile (passing it pins it like use_brand) |
aplus | boolean | also Amazon's 7 A+ modules: 1 brand hero and 7 brand promise at 21:9 (Premium full-width 1464x600 + mobile 600x450), 2-6 at 3:2 (key benefits, how to use, materials and details, lifestyle, what you get; Premium image-with-text 800x600, Basic header 970x600). With shots:[] only the A+ modules |
copy | object | the seller's own words for A+ text fields, by module id then field, e.g. {aplus_hero:{headline:'…'}}; each is clipped to Amazon's limit. Without it the fields are suggested only from the product's own data, never invented |
copyIn | "fields" | "image" | A+ words: 'fields' (default) = suggested for Amazon's text fields, none painted; 'image' = the words painted on the picture |
mainImage | string | an APPROVED main image (URL or Library id) to draw every other image from instead of rendering a new main |
mainJob | string | the mainJob id a previous call returned, when rendering its `remaining`: they are drawn from that main |
plan | object[] | the `plan` (or `remaining`) a previous call returned: render exactly those images, no new plan, with the same image |
dryRun | boolean | true = plan and quote only, nothing rendered or charged |
list_products#
List the product catalog
The brand's product catalog: each product's id, title, page link, price (and whether it is current), photos, its own selling points and audience, and when it was last checked against its live page. Free. `refresh:'stale'` re-reads rows older than a day first, `refresh:'all'` re-reads every page. Use the ids with make_static_ads.
| Parameter | Type | Description |
|---|
refresh | "stale" | "all" | re-read product pages before listing: 'stale' (older than a day) or 'all' |
brandId | string | a profile id/name from list_brands; omit for the active profile |
add_product#
Add a product from a link destructive
Add a product to the brand's catalog from its product-page link: reads the page's own data (name, every photo, price and currency, description, its bullet-point selling points), no model, 0 credits. Re-adding a link updates the row (the live page wins). Without a url, `title` adds one by hand. `audience` and `sellingPoints` you pass are kept through later re-reads.
| Parameter | Type | Description |
|---|
url | string | the product page link |
title | string | to add a product by hand (no link) |
images | string[] | photo urls for a hand-added product |
price | string | hand-added only; never printed as current unless read from a page |
currency | string | currency code for the price, e.g. USD |
description | string | product description |
sellingPoints | string[] | bullet-point selling points, one per item |
audience | string | who this product is for |
brandId | string | a profile id/name from list_brands; omit for the active profile |
refresh_products#
Re-check products against their pages destructive
Re-read product pages now (all products with a page, or `ids`) and update the catalog: the live page wins, a failed read is recorded and said. `sync:true` instead imports the whole store catalog (the brand's connected Shopify store, else its website's public catalog), merging into existing rows. Free.
| Parameter | Type | Description |
|---|
ids | string[] | product ids to re-read; omit to re-read every product that has a page |
sync | boolean | import the store catalog instead of re-reading pages |
brandId | string | a profile id/name from list_brands; omit for the active profile |
update_product#
Edit a product destructive
Edit a catalog product's title, description, selling points, audience or page link. What you set here is kept through later page re-reads. Free.
| Parameter | Type | Description |
|---|
idrequired | string | catalog product id, as add_product returned it |
title | string | product name |
description | string | product description |
sellingPoints | string[] | selling points; replaces the saved list |
audience | string | who this product is for |
url | string | product page link |
brandId | string | a profile id/name from list_brands; omit for the active profile |
remove_product#
Remove a product destructive
Remove one product from the brand's catalog (its ads already made stay in the Library). Free.
| Parameter | Type | Description |
|---|
idrequired | string | catalog product id to remove |
brandId | string | a profile id/name from list_brands; omit for the active profile |