Hermoso

Official52 toolsLive

by hermoso-ai · JavaScript

MCP server + CLI for Hermoso — research winning ads and generate finished image/video ads with AI

io.github.hermoso-ai/hermoso MCP Server

The MCP server + CLI for Hermoso enables research-winning ads generation and finished image/video ad creation using AI. It provides a Model Context Protocol interface to streamline model-driven ad assets, leveraging Claude and related AI components within a focused MCP workflow.

🛠️ Key Features

Model Context Protocol server implementation
Command-line interface for rapid interaction
AI-powered ad generation for images and videos
Integrates with research-focused ad workflows

🚀 Use Cases

Generate high-performing ad creatives from concise prompts
Produce finished ad assets for campaigns
Experiment with model contexts to optimize output quality

⚡ Developer Benefits

Clear MCP server structure for extensibility
Reusable components for model-context-driven rendering
Topics include ad-generation, MCP, and AI tooling for rapid iteration

⚠️ Limitations

Based on provided data; avoid extrapolation beyond described functionality
Specific model integrations or runtime constraints not detailed in source material

Topics

ad-generationadsaiclaudemcpmcp-servermodel-context-protocol

Captured live from the server via tools/list.

hermoso_capabilities

Probe what this Hermoso account can do RIGHT NOW: available image/video model ids + their exact credit costs, aspect ratios, video durations, the recipe ids, and the canEdit/canAvatar/canPublish flags. Call this FIRST so you generate with valid model ids and known costs. Read-only, free.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

hermoso_credits

Return the account credit balance, credits used this session, and recent priced calls. Check before kicking off paid generation.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

buy_credits

Out of credits? Get a ready-to-pay checkout link for a credit PACK. Call with no argument to list the available packs (id · credits · price); call again with `pack` set to a pack id to get a Stripe checkout URL. Hand that URL to your human — THEY pay on Stripe's secure hosted page (agents never spend money directly), and the credits land on this account the moment payment completes. Packs only; subscriptions are managed by a person in Settings → Billing. Nothing is charged until your human pays.

Parameters1

pack

string

optional

the pack id to buy (e.g. pack-2k) — omit to list the available packs first

Raw schema

{
  "type": "object",
  "properties": {
    "pack": {
      "description": "the pack id to buy (e.g. pack-2k) — omit to list the available packs first",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

billing_status

Show this account's billing at a glance: current plan (id + label + monthly price), credit balance, whether auto-reload is on, whether a card is on file, and whether YOU (this key) have ADMIN rights to change billing. Read-only, free. Call it before upgrade_plan / set_auto_reload to know what's possible — members have read-only billing.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

upgrade_plan

Change this account's SUBSCRIPTION plan (admin only). Call with no argument to list the plans (id · monthly price · monthly credits); call again with `plan` set to a plan id. A NEW subscriber gets a ready-to-pay Stripe Checkout URL to hand your human — THEY pay on Stripe (agents never spend money directly). If the account already has a paid plan, or you're DOWNGRADING, the change is made by a person in the app (Settings → Billing) and the tool returns exactly what to do. Members (read-only billing) get an honest 'ask an admin' message. Nothing is charged until your human pays.

Parameters2

plan	string	optional	the plan id to move to (e.g. pro) — omit to list the available plans first
period	string	optional	billing cadence — monthly (default) or yearly (2 months free)

Raw schema

{
  "type": "object",
  "properties": {
    "plan": {
      "description": "the plan id to move to (e.g. pro) — omit to list the available plans first",
      "type": "string"
    },
    "period": {
      "description": "billing cadence — monthly (default) or yearly (2 months free)",
      "type": "string",
      "enum": [
        "mo",
        "yr"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

set_auto_reload

Turn automatic credit reloads on or off (admin only): when the balance drops below a threshold, the card on file is charged for a top-up pack — SERVER-SIDE, even with no app open. Requires a saved card, added once in the app at first checkout/top-up; if there's none the tool tells you exactly where to add it. After that one-time card setup, agents can manage auto-reload, top-ups and plan links fully. Members (read-only billing) get an 'ask an admin' message.

Parameters3

enabled	boolean	required	true to turn auto-reload on, false to turn it off
thresholdCredits	integer	optional	reload when the balance drops below this many credits
reloadCredits	integer	optional	how many credits to add each reload — must match a credit pack size (see buy_credits)

Raw schema

{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "true to turn auto-reload on, false to turn it off"
    },
    "thresholdCredits": {
      "description": "reload when the balance drops below this many credits",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "reloadCredits": {
      "description": "how many credits to add each reload — must match a credit pack size (see buy_credits)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "enabled"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_brands

List every brand on this account (id + name) and which one this connection currently acts on. Multi-brand accounts: call this, then use_brand to switch. Read-only, free.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

use_brand

Pin which brand this connection generates for (multi-brand accounts). Pass the brand id or exact name from list_brands. Persists for this API key until changed.

Parameters1

brand

string

required

brand id (e.g. default / p_xxx) or its exact name from list_brands

Raw schema

{
  "type": "object",
  "properties": {
    "brand": {
      "type": "string",
      "description": "brand id (e.g. default / p_xxx) or its exact name from list_brands"
    }
  },
  "required": [
    "brand"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

plan_ad

Creative director: turn a brand + product/brief into a finished ad CONCEPT — copy variants (headline/primary/cta) plus an image_concept.prompt OR a video_storyboard, with the resolved recipe + the model ids to render with. Renders nothing; chain its output into generate_image / generate_video. Spends LLM tokens, 0 ScrapeCreators credits.

Parameters6

brand	any	optional	brand name, or a brand profile object {name,domain,category,palette,products,…}. OMIT to use the workspace’s SAVED brand + memory automatically (see get_brand); use draft_brand to onboard a new one
product	string	required	what to advertise + any angle/offer the user specified
format	string	optional	'image', 'video', or 'auto' when unspecified
recipe	string	optional	a recipe id from hermoso_capabilities to force an archetype
reference	string	optional	a reference ad URL to remix the angle from — Facebook Ad Library, LinkedIn Ad Library or Google Ads Transparency links (the real ad’s copy/advertiser are fetched and fed into the concept)
language	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "brand": {
      "description": "brand name, or a brand profile object {name,domain,category,palette,products,…}. OMIT to use the workspace’s SAVED brand + memory automatically (see get_brand); use draft_brand to onboard a new one",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "properties": {},
          "additionalProperties": {}
        }
      ]
    },
    "product": {
      "type": "string",
      "description": "what to advertise + any angle/offer the user specified"
    },
    "format": {
      "description": "'image', 'video', or 'auto' when unspecified",
      "type": "string",
      "enum": [
        "auto",
        "image",
        "video"
      ]
    },
    "recipe": {
      "description": "a recipe id from hermoso_capabilities to force an archetype",
      "type": "string"
    },
    "reference": {
      "description": "a reference ad URL to remix the angle from — Facebook Ad Library, LinkedIn Ad Library or Google Ads Transparency links (the real ad’s copy/advertiser are fetched and fed into the concept)",
      "type": "string"
    },
    "language": {
      "type": "string"
    }
  },
  "required": [
    "product"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

generate_image

Render a finished ad IMAGE and return its served URL. refImages (local paths or URLs) force product-accurate compositing (drops a real product into the scene). model = a catalog id from hermoso_capabilities (omit for the default). Fast (seconds). Spends credits.

Parameters6

prompt	string	required	the full image prompt — subject, composition, lighting, and any on-image ad text
refImages	array	optional	local file paths or URLs of product/logo references to composite in
useBrand	boolean	optional	default true: with no refImages, the server hydrates the SAVED brand’s product/logo references so the output lands on-brand; pass false for a pure prompt-only render
aspectRatio	string	optional	e.g. '1:1', '9:16', '16:9'
model	string	optional	image model id from hermoso_capabilities
imageSize	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "the full image prompt — subject, composition, lighting, and any on-image ad text"
    },
    "refImages": {
      "description": "local file paths or URLs of product/logo references to composite in",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "useBrand": {
      "description": "default true: with no refImages, the server hydrates the SAVED brand’s product/logo references so the output lands on-brand; pass false for a pure prompt-only render",
      "type": "boolean"
    },
    "aspectRatio": {
      "description": "e.g. '1:1', '9:16', '16:9'",
      "type": "string"
    },
    "model": {
      "description": "image model id from hermoso_capabilities",
      "type": "string"
    },
    "imageSize": {
      "type": "string"
    }
  },
  "required": [
    "prompt"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

generate_voice

RAW text-to-speech from the voice-model catalog: speak a script in a chosen voice and return the served MP3 URL. For a standalone voiceover / narration clip — NOT for adding audio to a video (render_ad and generate_video voice their own spots; change_voice re-voices a finished clip). engine picks the voice model (default 'seed-audio'; also 'eleven-v3', 'minimax-speech', 'kokoro'); voice is a preset name from that engine (see hermoso_capabilities → voice engines). Paid (a couple of credits by length; ≤900 characters).

Parameters3

text	string	required	the script to speak (≤900 characters)
engine	string	optional	voice-engine id: 'seed-audio' (default), 'eleven-v3', 'minimax-speech', or 'kokoro' — listed in hermoso_capabilities
voice	string	optional	a voice preset from the chosen engine (e.g. 'Aria'/'George' on eleven-v3, 'stokie_en' on seed-audio) — omit for the engine default

Raw schema

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "the script to speak (≤900 characters)"
    },
    "engine": {
      "description": "voice-engine id: 'seed-audio' (default), 'eleven-v3', 'minimax-speech', or 'kokoro' — listed in hermoso_capabilities",
      "type": "string"
    },
    "voice": {
      "description": "a voice preset from the chosen engine (e.g. 'Aria'/'George' on eleven-v3, 'stokie_en' on seed-audio) — omit for the engine default",
      "type": "string"
    }
  },
  "required": [
    "text"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

generate_text

RAW text generation against the writing-model catalog (Claude, Gemini, GPT, Llama, DeepSeek…) — ad copy, hooks, scripts, rewrites, brainstorms. Prompt-only, no ad assembly (for a finished on-brand creative use plan_ad → render_ad). model = a writing-model id from hermoso_capabilities (omit for the default Claude orchestrator). Paid (a credit or two by length).

Parameters2

prompt	string	required	the writing task / question
model	string	optional	a writing-model id from hermoso_capabilities (a Claude / Gemini / GPT / Llama / DeepSeek id) — omit for the default

Raw schema

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "the writing task / question"
    },
    "model": {
      "description": "a writing-model id from hermoso_capabilities (a Claude / Gemini / GPT / Llama / DeepSeek id) — omit for the default",
      "type": "string"
    }
  },
  "required": [
    "prompt"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

render_ad

RECOMMENDED for finished video ADS: render a plan_ad concept through the SAME quality pipeline as the Hermoso web Studio — timed shot list, exact/clean speech (no garbled words), text composited in post (never model-painted), brand end card, licensed music bed, real product references. Pass plan_ad’s full structured output as `creative`. Honors the plan’s render_plan structure/duration: a ≤15s storyboard renders as ONE single-pass clip; a longer plan automatically renders as STITCHED ACTS (fewest balanced ≤15s clips) — never time-compressed into one clip. Renders take 1–3 min; keep polling get_job if it returns still-rendering. Spends credits.

Parameters11

creative	object	required	the FULL structured output of plan_ad (must contain video_storyboard)
model	string	optional	video model id from hermoso_capabilities (default: the plan’s pick). Naming one is a DELIBERATE pick — the server asks before ever swapping it (no silent fallback)
durationSeconds	number	optional
aspectRatio	string	optional
resolution	string	optional	'720p' default; '480p' = cheap fast draft pass, '1080p'/'4k' = premium final delivery (more credits)
captions	boolean	optional	composited caption pills on/off (default: the recipe decides)
endCard	boolean	optional	branded end card on/off (default: on, except organic recipes)
music	boolean	optional	licensed music bed on/off (default on)
lockup	boolean	optional	persistent brand-logo lockup overlay on/off
ttsVoice	string	optional	voiceover voice name (e.g. Rachel / George) when the plan voices over
dryRun	boolean	optional	return the routing decision (single pass vs stitched acts, resolved model + act lengths) WITHOUT submitting a render — free, nothing charged

Raw schema

{
  "type": "object",
  "properties": {
    "creative": {
      "type": "object",
      "properties": {},
      "additionalProperties": {},
      "description": "the FULL structured output of plan_ad (must contain video_storyboard)"
    },
    "model": {
      "description": "video model id from hermoso_capabilities (default: the plan’s pick). Naming one is a DELIBERATE pick — the server asks before ever swapping it (no silent fallback)",
      "type": "string"
    },
    "durationSeconds": {
      "type": "number"
    },
    "aspectRatio": {
      "type": "string"
    },
    "resolution": {
      "description": "'720p' default; '480p' = cheap fast draft pass, '1080p'/'4k' = premium final delivery (more credits)",
      "type": "string",
      "enum": [
        "480p",
        "720p",
        "1080p",
        "4k"
      ]
    },
    "captions": {
      "description": "composited caption pills on/off (default: the recipe decides)",
      "type": "boolean"
    },
    "endCard": {
      "description": "branded end card on/off (default: on, except organic recipes)",
      "type": "boolean"
    },
    "music": {
      "description": "licensed music bed on/off (default on)",
      "type": "boolean"
    },
    "lockup": {
      "description": "persistent brand-logo lockup overlay on/off",
      "type": "boolean"
    },
    "ttsVoice": {
      "description": "voiceover voice name (e.g. Rachel / George) when the plan voices over",
      "type": "string"
    },
    "dryRun": {
      "description": "return the routing decision (single pass vs stitched acts, resolved model + act lengths) WITHOUT submitting a render — free, nothing charged",
      "type": "boolean"
    }
  },
  "required": [
    "creative"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

make_template_ad

Render a NATIVE-STYLE TEMPLATE ad from pure HTML — no AI video/image model in the loop, renders in ~30 seconds for a couple of credits. Perfect for native-feel social ads at volume. YOU author the content (short, casual, believable — never marketing-speak). Templates (pass as config.template): 'imessage-chat' (VIDEO ~15s: a real-looking iMessage thread where a friend reveals the product as a rich-link card; config: { thread: { contactName, messages: [{from:'them'|'me', text?, product?:{image,title,domain}}] }, theme?:'dark'|'light', endCard:{headline,cta,domain,logo?,color} } — 4-6 short lowercase bubbles, product card mid-thread from 'me', 1-2 excited replies after); 'chatgpt-chat' (VIDEO: a ChatGPT answer streams the punchline; config: { question, answer (may **bold** the brand), productImage?, endCard }); 'apple-notes' (VIDEO: an iPhone note types itself out; config: { title, lines: string[], theme?, endCard }); 'value-prop' (VIDEO ~17s kinetic typography: config: { hook (≤40 chars), claims: string[] (3-5 COMPLETE phrases, ≤6 words / ≤34 chars each — a finished thought, NEVER a clipped clause like 'Looks good on any'), productImages: string[] (2-3 DISTINCT photos — one rotates per card), palette: string[], endCard }); 'static-mockup' (IMAGE: config: { style:'imessage'|'notes'|'card', size?:{w,h}, ...style fields }); 'airdrop-carousel' (VIDEO ~10s: an iOS AirDrop share card springs up and cycles 3-16 REAL product photos to a full-lineup payoff; config: { brandName, products: [{image, title?}], contactLine?, endCard }); 'app-ui-tour' (VIDEO ~12-16s for APP brands: floating-iPhone mockup walks through REAL app screenshots with kinetic captions; config: { hook?, appName, iconImage?, beats: [{screenImage, caption}] (2-6), palette?, fontStack?, endCard }); 'imessage-cascade' (VIDEO ~12s: iOS notification banners spring in and stack over a blurred backdrop; config: { notifications: [{sender, text}] (4-8), backgroundImage?, endCard }); 'photo-grid' (VIDEO ~8s: collage assembles real photos one at a time; config: { title?, photos: [{image, label?}] (4-9), palette?, fontStack?, endCard }); 'vignette' (VIDEO ~12s: cinematic Ken-Burns hero film; config: { hook, lines: [2-4 ≤40ch], heroImage, palette?, fontStack?, endCard }); 'myth-vs-fact' (VIDEO ~15-26s VO-FIRST kinetic explainer with a real VOICEOVER — the family's ONE paid-audio format: a calm-authority read busts 2-4 myths, each MYTH line slamming in with a red per-line strike then the counter FACT line landing bold+affirmative, word-level KARAOKE lighting each word as the VO speaks it; config: { pairs: [{ myth (≤50ch, the common wrong belief), fact (≤60ch, the corrective truth — wrap its payoff phrase in [brackets] to accent it) }] (2-4), palette?, fontStack?, endCard }. Real product truths only — NEVER invent stats. Costs the flat template credits PLUS a small voiceover charge); 'carousel' (MULTI-IMAGE: 5-10 branded 1080×1080 PNG slides for Meta/LinkedIn/IG carousels — returns an images[] array, one PNG per slide; config: { cover: { hook?, title }, slides: [{ headline (≤8 words), support? (≤16 words), stat?: { value, label } }] (3-8; a stat slide is a REAL user-supplied number like '94%' or '40k+' + a label, never invented), cta: { headline, cta?, domain? }, productImage?, logo?, palette?, fontStack?, endCardColor? }). Image URLs may be any public URL — the server localizes them. Spends a couple of credits.

Parameters1

config

object

required

the template config — MUST include config.template (one of the template ids above) plus that template's fields

Raw schema

{
  "type": "object",
  "properties": {
    "config": {
      "type": "object",
      "properties": {},
      "additionalProperties": {},
      "description": "the template config — MUST include config.template (one of the template ids above) plus that template's fields"
    }
  },
  "required": [
    "config"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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, a couple of credits. 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.

Parameters7

videoUrl	string	required	the served URL of the video to finish (from a previous render/job)
header	string	optional	header pill copy, ≤40 chars (required when pills is on)
sub	string	optional	accent sub-pill copy, ≤34 chars (usually the product/brand)
points	array	optional	3-4 proof points, ≤44 chars each
accent	string	optional	brand accent hex for the sub-pill
pills	boolean	optional	default true — set false for a grain-only pass
grain	boolean	optional	default false — anti-AI film-grain finish

Raw schema

{
  "type": "object",
  "properties": {
    "videoUrl": {
      "type": "string",
      "description": "the served URL of the video to finish (from a previous render/job)"
    },
    "header": {
      "description": "header pill copy, ≤40 chars (required when pills is on)",
      "type": "string"
    },
    "sub": {
      "description": "accent sub-pill copy, ≤34 chars (usually the product/brand)",
      "type": "string"
    },
    "points": {
      "description": "3-4 proof points, ≤44 chars each",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "accent": {
      "description": "brand accent hex for the sub-pill",
      "type": "string"
    },
    "pills": {
      "description": "default true — set false for a grain-only pass",
      "type": "boolean"
    },
    "grain": {
      "description": "default false — anti-AI film-grain finish",
      "type": "boolean"
    }
  },
  "required": [
    "videoUrl"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

fix_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.

Parameters6

videoUrl	string	required	the served URL of the master video to fix
startSeconds	number	required	window start in seconds
endSeconds	number	required	window end in seconds (window 1.5-8s)
prompt	string	required	what the replacement footage should show — describe the shot, matching the master's style
refImage	string	optional	optional product/style anchor image URL
speechWindows	array	optional	[[start,end],...] windows with spoken lines — the fix window must not overlap these

Raw schema

{
  "type": "object",
  "properties": {
    "videoUrl": {
      "type": "string",
      "description": "the served URL of the master video to fix"
    },
    "startSeconds": {
      "type": "number",
      "description": "window start in seconds"
    },
    "endSeconds": {
      "type": "number",
      "description": "window end in seconds (window 1.5-8s)"
    },
    "prompt": {
      "type": "string",
      "description": "what the replacement footage should show — describe the shot, matching the master's style"
    },
    "refImage": {
      "description": "optional product/style anchor image URL",
      "type": "string"
    },
    "speechWindows": {
      "description": "[[start,end],...] windows with spoken lines — the fix window must not overlap these",
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "type": "number"
        }
      }
    }
  },
  "required": [
    "videoUrl",
    "startSeconds",
    "endSeconds",
    "prompt"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

generate_video

Render a RAW video clip from your own prompt and return its served mp4 URL. For finished brand ADS prefer render_ad (it runs the Studio quality pipeline — composited text, clean speech, end card, music); use this for raw/experimental clips or precise manual control. ONE generation = one continuous clip up to the model’s longest listed duration (seedance-2 goes to 15s single-pass with a full multi-beat arc — never assume a generic 8–10s cap); durationSeconds must be one of the model’s durations from hermoso_capabilities. Renders take 1–3 min. refImage anchors the opening frame; ttsScript adds a voiceover. Pass refVideo (a clip URL) to EDIT an existing video instead of generating from scratch — the omni engine transforms that clip per your prompt, inheriting the source clip’s canvas + length (aspectRatio/durationSeconds are ignored for an edit). Spends credits (Starter plan is video-blocked server-side).

Parameters10

prompt	string	required	the video prompt / shot description (for a refVideo edit, this is the transformation instruction)
refImage	string	optional	local path or URL to anchor the first frame
refVideo	string	optional	URL of an existing video to EDIT rather than generate from scratch — the omni engine accepts a raw clip and transforms it per your prompt, inheriting the SOURCE clip’s canvas (aspect ratio) and length (aspectRatio/durationSeconds are ignored for an edit). Omit to generate a fresh clip.
durationSeconds	number	optional	clip length in seconds
aspectRatio	string	optional	default '9:16'
model	string	optional	video model id from hermoso_capabilities. Naming one is a DELIBERATE pick — the server asks before ever swapping it (no silent fallback); omit it to let the router pick
resolution	string	optional	'720p' default; '480p' = cheap fast draft pass, '1080p'/'4k' = premium final delivery (more credits)
ttsScript	string	optional	voiceover script to speak
ttsVoice	string	optional	voice name, e.g. Rachel / George
musicMood	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "the video prompt / shot description (for a refVideo edit, this is the transformation instruction)"
    },
    "refImage": {
      "description": "local path or URL to anchor the first frame",
      "type": "string"
    },
    "refVideo": {
      "description": "URL of an existing video to EDIT rather than generate from scratch — the omni engine accepts a raw clip and transforms it per your prompt, inheriting the SOURCE clip’s canvas (aspect ratio) and length (aspectRatio/durationSeconds are ignored for an edit). Omit to generate a fresh clip.",
      "type": "string"
    },
    "durationSeconds": {
      "description": "clip length in seconds",
      "type": "number"
    },
    "aspectRatio": {
      "description": "default '9:16'",
      "type": "string"
    },
    "model": {
      "description": "video model id from hermoso_capabilities. Naming one is a DELIBERATE pick — the server asks before ever swapping it (no silent fallback); omit it to let the router pick",
      "type": "string"
    },
    "resolution": {
      "description": "'720p' default; '480p' = cheap fast draft pass, '1080p'/'4k' = premium final delivery (more credits)",
      "type": "string",
      "enum": [
        "480p",
        "720p",
        "1080p",
        "4k"
      ]
    },
    "ttsScript": {
      "description": "voiceover script to speak",
      "type": "string"
    },
    "ttsVoice": {
      "description": "voice name, e.g. Rachel / George",
      "type": "string"
    },
    "musicMood": {
      "type": "string"
    }
  },
  "required": [
    "prompt"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

generate_avatar

Render a TALKING-AVATAR / creator lip-sync clip from a portrait image + a script. Blocks until done (1–3 min). Requires the avatar capability (canAvatar in hermoso_capabilities). Spends credits.

Parameters4

image	string	required	local path or URL of the presenter portrait
script	string	required	the words the avatar speaks
voice	string	optional	voice name (Rachel/Sarah/George/Adam)
resolution	string	optional	'720p' (default) or '480p' draft

Raw schema

{
  "type": "object",
  "properties": {
    "image": {
      "type": "string",
      "description": "local path or URL of the presenter portrait"
    },
    "script": {
      "type": "string",
      "description": "the words the avatar speaks"
    },
    "voice": {
      "description": "voice name (Rachel/Sarah/George/Adam)",
      "type": "string"
    },
    "resolution": {
      "description": "'720p' (default) or '480p' draft",
      "type": "string"
    }
  },
  "required": [
    "image",
    "script"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

stitch_video

Render a multi-scene STITCHED video (≥2 scenes) — ONLY for spots LONGER than one model clip (>15s). A ≤15s multi-beat ad renders better and cheaper as ONE single-pass generate_video/render_ad on seedance-2 (it handles the full hook→demo→payoff arc in one take) — never stitch those. Blocks until done. Spends credits.

Parameters7

scenes	array	required	array of scene objects (visual + optional voiceover/seconds)
aspectRatio	string	optional
voiceover	string	optional
voice	string	optional
resolution	string	optional
model	string	optional
durationSeconds	number	optional

Raw schema

{
  "type": "object",
  "properties": {
    "scenes": {
      "minItems": 2,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {},
        "additionalProperties": {}
      },
      "description": "array of scene objects (visual + optional voiceover/seconds)"
    },
    "aspectRatio": {
      "type": "string"
    },
    "voiceover": {
      "type": "string"
    },
    "voice": {
      "type": "string"
    },
    "resolution": {
      "type": "string"
    },
    "model": {
      "type": "string"
    },
    "durationSeconds": {
      "type": "number"
    }
  },
  "required": [
    "scenes"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_job

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.

Parameters1

string

required

the job id, e.g. job_xxx

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the job id, e.g. job_xxx"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_skills

List the bundled Hermoso SKILLS — multi-step workflow instructions (SKILL.md) that orchestrate the other tools (research an ad space, plan+render a finished ad, product photoshoot, raw generation) — plus the in-app strategy skills and creative recipes. Call get_skill to load a bundle. Read-only, free.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_skill

Load a bundled skill’s full SKILL.md workflow instructions by name (from list_skills). Follow the loaded instructions to run that workflow with the other tools. Read-only, free.

Parameters1

name

string

required

bundle name from list_skills, e.g. hermoso-generate

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "bundle name from list_skills, e.g. hermoso-generate"
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_jobs

List the most recent render jobs + how many are currently running, so you can report on or resume in-flight work.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

find_competitors

Discover a brand's competitor / similar / adjacent brands from its domain (Claude grounded by web search). mode=competitors (default, excludes the searched company), inspiration (best relevant ads incl. it), or company. 0 ScrapeCreators credits.

Parameters2

domain	string	required	the brand domain, e.g. flourish.com
mode	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "the brand domain, e.g. flourish.com"
    },
    "mode": {
      "type": "string",
      "enum": [
        "competitors",
        "inspiration",
        "company"
      ]
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

pull_competitor_ads

Pull a brand's real running ads across Meta / Google / LinkedIn ad libraries (deduped, sorted, right page resolved). Spends ScrapeCreators credits.

Parameters6

companyName	string	optional	the advertiser name
domain	string	optional	the advertiser domain
platforms	array	optional	default ['facebook']; add 'google','linkedin'
country	string	optional	2-letter, default 'US'
limit	number	optional
sort	string	optional	'longest_running' (default) etc.

Raw schema

{
  "type": "object",
  "properties": {
    "companyName": {
      "description": "the advertiser name",
      "type": "string"
    },
    "domain": {
      "description": "the advertiser domain",
      "type": "string"
    },
    "platforms": {
      "description": "default ['facebook']; add 'google','linkedin'",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "country": {
      "description": "2-letter, default 'US'",
      "type": "string"
    },
    "limit": {
      "type": "number"
    },
    "sort": {
      "description": "'longest_running' (default) etc.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

research_ads

Natural-language ad research: a Claude tool-use loop over Meta/Google/LinkedIn ad libraries + organic TikTok. Returns a summary + the found ads (with their served URLs). Spends LLM tokens + ScrapeCreators credits.

Parameters2

query	string	required	what to research, e.g. "the longest-running protein-pancake ads on Meta"
brand	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "what to research, e.g. \"the longest-running protein-pancake ads on Meta\""
    },
    "brand": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "properties": {},
          "additionalProperties": {}
        }
      ]
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_meta_ads

Structured Meta (Facebook/Instagram) Ad Library pull — use when you know exactly WHAT to fetch: a keyword (query) OR one advertiser (companyName / pageId). Returns compact JSON {page_name, body, cta, link, dates, media} per ad. For open-ended research that needs judgment across platforms, use research_ads instead. Spends ScrapeCreators credits (~1–2).

Parameters7

query	string	optional	keyword search across ALL advertisers (use INSTEAD of companyName/pageId)
companyName	string	optional	one advertiser’s ads by brand name
pageId	string	optional	one advertiser’s ads by Facebook page id (most precise)
country	string	optional	2-letter code or 'ALL' (default ALL)
status	string	optional	ACTIVE = currently running; default ALL (includes proven past winners)
mediaType	string	optional
limit	integer	optional	max ads returned (1–25, default 8)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "keyword search across ALL advertisers (use INSTEAD of companyName/pageId)",
      "type": "string"
    },
    "companyName": {
      "description": "one advertiser’s ads by brand name",
      "type": "string"
    },
    "pageId": {
      "description": "one advertiser’s ads by Facebook page id (most precise)",
      "type": "string"
    },
    "country": {
      "description": "2-letter code or 'ALL' (default ALL)",
      "type": "string"
    },
    "status": {
      "description": "ACTIVE = currently running; default ALL (includes proven past winners)",
      "type": "string",
      "enum": [
        "ACTIVE",
        "INACTIVE",
        "ALL"
      ]
    },
    "mediaType": {
      "type": "string",
      "enum": [
        "ALL",
        "IMAGE",
        "VIDEO",
        "MEME",
        "IMAGE_AND_MEME",
        "NONE"
      ]
    },
    "limit": {
      "description": "max ads returned (1–25, default 8)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_google_ads

Structured Google Ads Transparency pull for ONE advertiser (by domain or advertiserId) — use when you know the brand; use research_ads for open-ended research. Deliberately fetches the cheap BASIC listing (get_ad_details=false, ~1 credit — the detailed variant with per-ad headlines costs 25 credits/call and is not exposed here). Returns compact JSON {advertiser, format, adUrl, image, firstShown, lastShown} per ad.

Parameters4

domain	string	optional	the advertiser's domain, e.g. nike.com
advertiserId	string	optional	Google advertiser id (AR…) when the domain is ambiguous
region	string	optional	2-letter region, default US
limit	integer	optional	max ads returned (1–25, default 8)

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "description": "the advertiser's domain, e.g. nike.com",
      "type": "string"
    },
    "advertiserId": {
      "description": "Google advertiser id (AR…) when the domain is ambiguous",
      "type": "string"
    },
    "region": {
      "description": "2-letter region, default US",
      "type": "string"
    },
    "limit": {
      "description": "max ads returned (1–25, default 8)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_linkedin_ads

Structured LinkedIn Ad Library search by company name, keyword, or companyId — use for a targeted B2B pull; use research_ads for open-ended research. Returns compact JSON {advertiser, headline, description, cta, link, media, dates, impressions} per ad — LinkedIn is the one library exposing real impression counts. Spends ScrapeCreators credits (~1).

Parameters5

company	string	optional	advertiser company name
keyword	string	optional	keyword across all advertisers
companyId	string	optional
countries	string	optional	CSV of 2-letter codes like 'US,CA'; omit or 'ALL' = worldwide
limit	integer	optional	max ads returned (1–25, default 8)

Raw schema

{
  "type": "object",
  "properties": {
    "company": {
      "description": "advertiser company name",
      "type": "string"
    },
    "keyword": {
      "description": "keyword across all advertisers",
      "type": "string"
    },
    "companyId": {
      "type": "string"
    },
    "countries": {
      "description": "CSV of 2-letter codes like 'US,CA'; omit or 'ALL' = worldwide",
      "type": "string"
    },
    "limit": {
      "description": "max ads returned (1–25, default 8)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_tiktok

Organic TikTok keyword search (there is NO TikTok ad library) — top-performing videos to mine for hooks/trends/remixable creative. Returns compact JSON {desc, author, handle, plays, likes, link, cover} per video, ranked by plays. Use research_ads for open-ended research. Spends ScrapeCreators credits (~1).

Parameters2

query	string	required	keyword or hashtag (no # needed)
limit	integer	optional	max videos returned (1–25, default 8)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "keyword or hashtag (no # needed)"
    },
    "limit": {
      "description": "max videos returned (1–25, default 8)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_instagram

Organic Instagram REELS keyword search (/v2/instagram/reels/search — ScrapeCreators' only IG keyword surface; profile/hashtag pulls go through scrapecreators_fetch with a handle). Returns compact JSON {desc, author, handle, plays, likes, link, cover} per reel, ranked by plays. Spends ScrapeCreators credits (~1).

Parameters2

query	string	required	keyword to search reels for
limit	integer	optional	max reels returned (1–25, default 8)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "keyword to search reels for"
    },
    "limit": {
      "description": "max reels returned (1–25, default 8)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_youtube

Organic YouTube keyword search (/v1/youtube/search) — videos to mine for hooks/angles/long-form structure. Returns compact JSON {desc (title), author, handle, plays, link, cover} per video, ranked by views. Spends ScrapeCreators credits (~1).

Parameters2

query	string	required	keyword to search videos for
limit	integer	optional	max videos returned (1–25, default 8)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "keyword to search videos for"
    },
    "limit": {
      "description": "max videos returned (1–25, default 8)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_reddit

Reddit keyword search (/v1/reddit/search, top-ranked) — a goldmine for the customer's OWN words (pain points, objections, language) to mine into ad hooks and copy. Returns compact JSON {desc (title+selftext), subreddit, upvotes, comments, link} per post. Spends ScrapeCreators credits (~1).

Parameters2

query	string	required	what to search Reddit for
limit	integer	optional	max posts returned (1–25, default 8)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "what to search Reddit for"
    },
    "limit": {
      "description": "max posts returned (1–25, default 8)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_threads

Organic Threads keyword search (/v1/threads/search) — short-form text/social posts for trend + voice research. Returns compact JSON {desc, author, handle, likes, link, cover} per post. Spends ScrapeCreators credits (~1).

Parameters2

query	string	required	keyword to search Threads for
limit	integer	optional	max posts returned (1–25, default 8)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "keyword to search Threads for"
    },
    "limit": {
      "description": "max posts returned (1–25, default 8)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

scrapecreators_fetch

Generic ScrapeCreators escape hatch for any ALLOWLISTED long-tail endpoint the dedicated search_* tools don't cover — e.g. {path:'/v1/instagram/profile', params:{handle:'nike'}}. Allowlisted platform families: TikTok (+ TikTok Shop), Instagram, YouTube, Facebook (organic profiles/posts/events/marketplace), LinkedIn (organic posts/companies), Twitter/X, Reddit, Threads, Snapchat, Pinterest, Twitch, Bluesky, Truth Social, Rumble, Spotify, SoundCloud, GitHub, Google search, link-in-bio pages (Linktree etc.). Param names vary per endpoint (profiles use `handle`, keyword searches use `query`, Reddit uses `subreddit`). WARNING: returns RAW provider JSON — large and messy; prefer the dedicated search_* tools. Spends ScrapeCreators credits.

Parameters2

path	string	required	exact SC endpoint path, e.g. '/v1/tiktok/profile' — non-allowlisted paths are rejected
params	object	optional	endpoint query params, e.g. {handle:'nike'}

Raw schema

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "exact SC endpoint path, e.g. '/v1/tiktok/profile' — non-allowlisted paths are rejected"
    },
    "params": {
      "description": "endpoint query params, e.g. {handle:'nike'}",
      "type": "object",
      "properties": {},
      "additionalProperties": {}
    }
  },
  "required": [
    "path"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_brand

What Hermoso ALREADY KNOWS for this account/workspace — the same saved brand profile (products, logos, palette, positioning) + learned memory the web Studio uses. Call this FIRST: if hasBrand is true you can omit brand everywhere; if false, onboard with draft_brand. 0 credits.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

draft_brand

Onboard a brand profile — from a website domain, a free-text description, or a social handle — into a {name, products, logo, …} object you can pass to plan_ad / generate. 0 ScrapeCreators credits. IMPORTANT: a domain can resolve to a DIFFERENT company than intended (e.g. bala.com is an engineering firm, not the Bala fitness brand at shopbala.com). Before spending any credits on research or renders, VERIFY the returned `name` (and `summary`) match the brand the user meant; if it looks wrong, re-draft with the correct domain or a description (pass save:false until confirmed) — this tool cannot ask the user, so the caller owns that check.

Parameters5

domain	string	optional	a website to scrape
description	string	optional	a free-text brand description (no website)
socialHandle	string	optional
platform	string	optional	platform for socialHandle (instagram/tiktok/…)
save	boolean	optional	save as the workspace’s brand (like Studio onboarding) so plan_ad/create use it automatically. Default: saves only when NO brand is saved yet; pass true to overwrite, false to never save

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "description": "a website to scrape",
      "type": "string"
    },
    "description": {
      "description": "a free-text brand description (no website)",
      "type": "string"
    },
    "socialHandle": {
      "type": "string"
    },
    "platform": {
      "description": "platform for socialHandle (instagram/tiktok/…)",
      "type": "string"
    },
    "save": {
      "description": "save as the workspace’s brand (like Studio onboarding) so plan_ad/create use it automatically. Default: saves only when NO brand is saved yet; pass true to overwrite, false to never save",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

fetch_asset

Resolve a generated asset reference (a /generated/… path or any URL) to a clickable absolute URL + a direct download URL.

Parameters2

url	string	required	the asset url or /generated/ path
name	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "the asset url or /generated/ path"
    },
    "name": {
      "type": "string"
    }
  },
  "required": [
    "url"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

analyze_video

Break a video ad down into its structure: the verbatim transcript (voiceover + on-screen text) with a beat list, plus duration and sampled frame timestamps. Use to study a reference/competitor ad before remixing its structure. Costs ~a transcription call; no ScrapeCreators credits.

Parameters1

url

string

required

the video URL (a served /generated/ path or a public http(s) video)

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "the video URL (a served /generated/ path or a public http(s) video)"
    }
  },
  "required": [
    "url"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters3

url	string	required	the ad asset URL (a /generated/ path or public URL)
kind	string	optional
intent	string	optional	what the ad is trying to achieve, for goal-fit scoring

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "the ad asset URL (a /generated/ path or public URL)"
    },
    "kind": {
      "type": "string",
      "enum": [
        "image",
        "video"
      ]
    },
    "intent": {
      "description": "what the ad is trying to achieve, for goal-fit scoring",
      "type": "string"
    }
  },
  "required": [
    "url"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

reframe_video

Reframe a video to a different aspect ratio (e.g. 16:9 master → 9:16 vertical) with smart subject tracking. Paid render; returns the served URL of the reframed video.

Parameters2

video	string	required	the source video URL
aspectRatio	string	required	the target aspect ratio

Raw schema

{
  "type": "object",
  "properties": {
    "video": {
      "type": "string",
      "description": "the source video URL"
    },
    "aspectRatio": {
      "type": "string",
      "enum": [
        "9:16",
        "1:1",
        "16:9",
        "4:3",
        "3:4",
        "21:9",
        "9:21"
      ],
      "description": "the target aspect ratio"
    }
  },
  "required": [
    "video",
    "aspectRatio"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

upscale_video

Upscale a video to higher resolution (2x) for final delivery. Paid render; returns the served URL.

Parameters1

video

string

required

the source video URL

Raw schema

{
  "type": "object",
  "properties": {
    "video": {
      "type": "string",
      "description": "the source video URL"
    }
  },
  "required": [
    "video"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

dub_video

Remake a finished video ad's voiceover in another language (translated script, re-voiced, re-muxed). Paid; returns the served URL of the localized video.

Parameters3

video	string	required	the source video URL
language	string	required	target language, e.g. 'Spanish', 'de', 'French (Canada)'
script	string	optional	the original spoken script if known — improves translation fidelity

Raw schema

{
  "type": "object",
  "properties": {
    "video": {
      "type": "string",
      "description": "the source video URL"
    },
    "language": {
      "type": "string",
      "description": "target language, e.g. 'Spanish', 'de', 'French (Canada)'"
    },
    "script": {
      "description": "the original spoken script if known — improves translation fidelity",
      "type": "string"
    }
  },
  "required": [
    "video",
    "language"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

change_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.

Parameters2

video	string	required	the source video URL
voice	string	optional	target narrator voice preset name, e.g. 'Aria', 'George', 'Rachel', 'Sarah', 'Brian', 'Charlotte' (defaults to a warm female read)

Raw schema

{
  "type": "object",
  "properties": {
    "video": {
      "type": "string",
      "description": "the source video URL"
    },
    "voice": {
      "description": "target narrator voice preset name, e.g. 'Aria', 'George', 'Rachel', 'Sarah', 'Brian', 'Charlotte' (defaults to a warm female read)",
      "type": "string"
    }
  },
  "required": [
    "video"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

recast_motion

Motion transfer: re-perform a reference video's motion with a different person/character (supply their image). The reference clip drives the movement; the image supplies the identity. Paid render.

Parameters4

image	string	required	the actor/character image URL (who should appear)
video	string	required	the reference video whose motion to re-perform
prompt	string	optional	optional scene/style guidance
orientation	string	optional	which aspect to keep: the video's (default) or the image's

Raw schema

{
  "type": "object",
  "properties": {
    "image": {
      "type": "string",
      "description": "the actor/character image URL (who should appear)"
    },
    "video": {
      "type": "string",
      "description": "the reference video whose motion to re-perform"
    },
    "prompt": {
      "description": "optional scene/style guidance",
      "type": "string"
    },
    "orientation": {
      "description": "which aspect to keep: the video's (default) or the image's",
      "type": "string",
      "enum": [
        "video",
        "image"
      ]
    }
  },
  "required": [
    "image",
    "video"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

plan_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.

Parameters4

brand	any	optional	brand name or profile object; OMIT to use the workspace’s saved brand
product	string	required	what to advertise
count	integer	optional	how many distinct variants (default 6)
language	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "brand": {
      "description": "brand name or profile object; OMIT to use the workspace’s saved brand",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "properties": {},
          "additionalProperties": {}
        }
      ]
    },
    "product": {
      "type": "string",
      "description": "what to advertise"
    },
    "count": {
      "description": "how many distinct variants (default 6)",
      "type": "integer",
      "minimum": 2,
      "maximum": 8
    },
    "language": {
      "type": "string"
    }
  },
  "required": [
    "product"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

competitor_teardown

Tear a competitor's ad strategy down into an actionable playbook: their opening-hook MIX, longest-running campaign THEMES, the WHITE SPACE nobody in their set runs, 2-3 render-ready COUNTER-PLAYS, and the territories they own that you should avoid. Pass `competitor` {name, domain?}. CONTRACT: supply `ads` (raw ad objects from a prior pull_competitor_ads / search_meta_ads call) to tear exactly those down, OR omit `ads` and this pulls the competitor's real Meta ads first (spends ~1-2 ScrapeCreators credits, longest-running = proven winners). Auto-tailors the white space + counter-plays to YOUR saved brand. Spends LLM tokens (0 SC credits when you pass ads).

Parameters3

competitor	object	required	the competitor to tear down
ads	array	optional	ad objects to tear down (from pull_competitor_ads / search_meta_ads). Omit to auto-pull their Meta ads first.
language	string	optional	output language (default English)

Raw schema

{
  "type": "object",
  "properties": {
    "competitor": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "the competitor brand name"
        },
        "domain": {
          "description": "their domain — sharpens the auto-pull page match",
          "type": "string"
        }
      },
      "required": [
        "name"
      ],
      "description": "the competitor to tear down"
    },
    "ads": {
      "description": "ad objects to tear down (from pull_competitor_ads / search_meta_ads). Omit to auto-pull their Meta ads first.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {},
        "additionalProperties": {}
      }
    },
    "language": {
      "description": "output language (default English)",
      "type": "string"
    }
  },
  "required": [
    "competitor"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

check_ad_policy

Pre-flight ad copy against Meta's REAL, live Advertising Standards before you run it — a flat 1-credit check. Pulls Meta's actual policy pages and returns a verdict (pass / fix / block) where every flagged issue QUOTES Meta's own policy text verbatim plus a compliant rewrite that keeps the sell. It's a check, not an edit — it never changes the creative. Especially worth running for regulated-adjacent categories (health/supplements, weight-loss or beauty results claims, finance/crypto/insurance, alcohol, dating, gambling) or ANY strong/absolute/guaranteed claim.

Parameters4

copy	string	required	the ad copy / script / on-screen text to check
claims	string	optional	the claims / proof points the ad makes
category	string	optional	the product category — helps pick the relevant policy pages
imageDescription	string	optional	a description of the creative / image when relevant

Raw schema

{
  "type": "object",
  "properties": {
    "copy": {
      "type": "string",
      "description": "the ad copy / script / on-screen text to check"
    },
    "claims": {
      "description": "the claims / proof points the ad makes",
      "type": "string"
    },
    "category": {
      "description": "the product category — helps pick the relevant policy pages",
      "type": "string"
    },
    "imageDescription": {
      "description": "a description of the creative / image when relevant",
      "type": "string"
    }
  },
  "required": [
    "copy"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

remix_static

One-click STATIC-AD REMIX: rebuild a competitor/reference STATIC (image) ad as an on-brand version — SAME layout, composition and energy, but YOUR product, brand colours, logo and voice, with every trace of the source brand removed. Pass `imageUrl` = the static ad image to remix. Uses your saved brand (pass brandId to target a specific brand — that switches this key's active brand like use_brand). IMAGES ONLY — for video ads use render_ad. Bills as one image generation.

Parameters2

imageUrl	string	required	the URL of the static ad image to remix
brandId	string	optional	a brand id/name from list_brands to remix for; omit to use the active brand

Raw schema

{
  "type": "object",
  "properties": {
    "imageUrl": {
      "type": "string",
      "description": "the URL of the static ad image to remix"
    },
    "brandId": {
      "description": "a brand id/name from list_brands to remix for; omit to use the active brand",
      "type": "string"
    }
  },
  "required": [
    "imageUrl"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

mine_angles

Mine ad ANGLES from real customer language: gathers the customer's own words (Reddit, TikTok, the brand's review page + review-site results) and returns a RANKED angle bank — each angle tagged (pain / outcome / identity / fear / competitive-displacement / social-proof / contrast), 2-5 VERBATIM proof quotes, a 0-100 score with breakdown, and a ready-to-run hook in the customer's own voice. Reads YOUR saved brand (pass brandId to target a specific brand — that switches this key's active brand like use_brand). To tear down a COMPETITOR use competitor_teardown instead. Spends a few ScrapeCreators credits + LLM tokens.

Parameters1

brandId

string

optional

a brand id/name from list_brands to mine for; omit to use the active brand

Raw schema

{
  "type": "object",
  "properties": {
    "brandId": {
      "description": "a brand id/name from list_brands to mine for; omit to use the active brand",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_product_photos

List the product photos ALREADY saved in your workspace — the brand's product library plus any app-store screens (also surfaces photos locked in your OTHER creations, since a set product lands in the shared library). FREE — returns each photo's url + label. Call it before set_product_image to see the existing photos you can reuse. Reads YOUR saved brand (pass brandId to target a specific brand — that switches this key's active brand like use_brand).

Parameters1

brandId

string

optional

a brand id/name from list_brands whose product library to list; omit to use the active brand

Raw schema

{
  "type": "object",
  "properties": {
    "brandId": {
      "description": "a brand id/name from list_brands whose product library to list; omit to use the active brand",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

set_product_image

Lock an image as the ad's real PRODUCT photo so every render grounds on the true packaging. Pass `imageUrl` = a product shot's URL — an image from a prior research result (an organic Instagram/TikTok post, a scraped page image), a workspace / list_product_photos url, or any public product photo. The server downloads it and runs a product+safety check: a lifestyle/scene shot with no clear product, or an off-category / unsafe image, is REJECTED and NOTHING is locked (the summary says why). On PASS it persists the photo to a DURABLE url and returns it — pass that url as a reference to generate_image / render_ad. Bills one vision check. Reads YOUR saved brand for the category match (pass brandId to target a specific brand — switches this key's active brand like use_brand).

Parameters3

imageUrl	string	required	the image URL to lock as the product (from a research result, a workspace / list_product_photos url, or any public product photo)
source_note	string	optional	a short note on where it came from, e.g. "from their IG post"
brandId	string	optional	a brand id/name from list_brands to lock the product for; omit to use the active brand

Raw schema

{
  "type": "object",
  "properties": {
    "imageUrl": {
      "type": "string",
      "description": "the image URL to lock as the product (from a research result, a workspace / list_product_photos url, or any public product photo)"
    },
    "source_note": {
      "description": "a short note on where it came from, e.g. \"from their IG post\"",
      "type": "string"
    },
    "brandId": {
      "description": "a brand id/name from list_brands to lock the product for; omit to use the active brand",
      "type": "string"
    }
  },
  "required": [
    "imageUrl"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md4 KBView on GitHub

Hermoso — MCP, CLI & Skills

Drive Hermoso — the AI ad studio — from any AI agent: Claude Code, Claude.ai, Cursor, Codex, or your own scripts. Research the ads already winning in a market, plan a creative, and generate finished image & video ads (your real product composited in, copy + CTA included) — all over MCP tools, a CLI, or installable Claude skills.

Instant: the hosted Claude.ai connector

Paste https://app.hermoso.ai/mcp into Claude → Settings → Connectors → Add custom connector, approve with your Hermoso account, done — all 22 tools with your saved brand context, billed to your plan.

Quickstart for Claude Code / Cursor / scripts (2 minutes)

Get an account at app.hermoso.ai — free tier included; plans & credits are the same ones the web Studio uses.
Create an agent key: app.hermoso.ai → Settings → Agents & API → Create API key (hmk_…).
Connect (Claude Code shown; any MCP client works):

bash

git clone https://github.com/hermoso-ai/hermoso.git && cd hermoso && npm install
claude mcp add hermoso -e HERMOSO_TOKEN=hmk_… -- node "$(pwd)/mcp/hermoso-mcp.mjs"

Your agent now has the full studio with your workspace's context: the brand profile, products, logos and learned memory you set up in the web app apply automatically (get_brand shows what's saved; omit brand in plan_ad/plan_variations to use it). Renders bill your Hermoso credits — same prices as the Studio.

1. MCP server (stdio) — Claude Code / Cursor / Codex

mcp/hermoso-mcp.mjs is a stdio MCP server exposing 22 tools.

bash

npm install
claude mcp add hermoso -- node "$(pwd)/mcp/hermoso-mcp.mjs"

Cursor / Codex — add to mcp.json (Codex uses the TOML equivalent):

json

{ "mcpServers": { "hermoso": { "command": "node", "args": ["<repo>/mcp/hermoso-mcp.mjs"],
  "env": { "HERMOSO_API_BASE": "https://app.hermoso.ai", "HERMOSO_TOKEN": "<your token>" } } } }

Then ask your agent: “Generate an image ad with Hermoso.”

Tools (22): hermoso_capabilities, hermoso_credits, get_brand, plan_ad, plan_variations, generate_image, generate_video, generate_avatar, stitch_video, reframe_video, upscale_video, dub_video, recast_motion, analyze_video, score_ad, get_job, list_jobs, find_competitors, pull_competitor_ads, research_ads, draft_brand, fetch_asset. Call hermoso_capabilities first — it returns valid model ids and per-render credit costs. Render jobs queue server-side and poll to completion, returning a served URL.

2. CLI — the token-cheap path for terminal agents

bin/hermoso.mjs mirrors the tools as subprocess commands, so an agent can shell out instead of carrying a fat tool manifest.

bash

npm install -g .                                   # installs `hermoso`
hermoso capabilities                               # valid model ids + costs (run first)
hermoso create --brand "YourBrand" --product "your best-selling product" --format image
hermoso generate image --prompt "…" --ref ./product.png --wait
hermoso generate video --prompt "…" --duration 8 --wait
hermoso competitors yourbrand.com
hermoso research "Liquid Death’s longest-running ads"

Add --json to any command for machine output.

3. Claude skills — slash commands that wrap the CLI

skills/ holds four installable skills: hermoso-generate, hermoso-ad-from-brand, hermoso-product-photoshoot, hermoso-research.

bash

cp -r skills/* ~/.claude/skills/

Then invoke /hermoso-ad-from-brand an ad for yourbrand.com — our hero product.

Configuration

Env	Meaning
`HERMOSO_API_BASE`	The Hermoso API origin (default `https://app.hermoso.ai` — set `http://localhost:3000` if you run the app yourself)
`HERMOSO_TOKEN`	Bearer token — required against the hosted app (rolling out)
`HERMOSO_PROFILE`	Brand-workspace id, for accounts with multiple brand profiles

mcp/http.mjs is the hosted remote-connector transport (paste-a-URL into Claude.ai → Connectors). It ships in this repo for transparency and refuses to mount without authenticated identity — no anonymous spend, ever.

License

MIT © Hermoso

Install

Tools (52)

hermoso_capabilitieshermoso_creditsbuy_creditsbilling_statusupgrade_planset_auto_reloadlist_brandsuse_brand

Configuration

Environment variables

HERMOSO_TOKENsecret

Hermoso agent key (hmk_…) from app.hermoso.ai → Settings → Agents & API. Required against the hosted app.

HERMOSO_API_BASE

Hermoso API origin. Defaults to https://app.hermoso.ai; set http://localhost:3000 to run against your own server.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "hermoso": {
      "command": "npx",
      "args": [
        "-y",
        "hermoso@0.1.5",
        "mcp"
      ],
      "env": {
        "HERMOSO_TOKEN": "<YOUR_HERMOSO_TOKEN>",
        "HERMOSO_API_BASE": "<YOUR_HERMOSO_API_BASE>"
      }
    }
  }
}