Skip to main content
Higgsfield MCP logo
  • Category: model context protocol
  • Auth: DCR_OAUTH
  • Composio-managed OAuth available? No
  • Tools: 101
  • Triggers: 0
  • Slug: HIGGSFIELD_MCP
  • Version: 20261018_00

Tools

Slug: HIGGSFIELD_MCP_ANIMATION_ACTIONSRead-only catalog of the 3D rig animation library (678 actions: locomotion, gestures, dancing, combat, daily actions). Search by name or browse by group/category to find the animation_action_id for 3D generation with enable_animation=true. Each result has a preview_url GIF — when several candidates fit (e.g. many Idle or Walk variants), show the user the previews as markdown images and let them pick instead of choosing blindly. Does not create jobs.

Input Parameters

string
Pagination cursor (next_page_token from a previous result).
string
Filter by top-level group: WalkAndRun, BodyMovements, DailyActions, Dancing, Fighting.
integer
Max results, default 20.
string
Search term matched against action name and category, e.g. ‘walk’, ‘backflip’, ‘sword attack’. Omit to browse.
string
Filter by category, e.g. Walking, Running, Jumping, Idle, Dancing, Punching (see categories in the result).

Output

array
required
array
required
All filterable group values.
boolean
required
array
required
All filterable category values.
number
required
string
Slug: HIGGSFIELD_MCP_APPS_DESCRIBEGet an app’s action contract: with action, the full input/output schema + execution mode for that one action; without it, a summary of every action. Also returns manifest_revision, which apps_invoke requires. Read-only.

Input Parameters

string
Action name. Omit to list all actions in summary.
string
required
App UUID from apps_search.

Output

string
string
string
string
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Slug: HIGGSFIELD_MCP_APPS_INVOKERun one described action on a Marketplace app AS the current user. First call apps_describe(app_id, action) to get the exact arguments schema and the manifest_revision, then pass them here. Long-running actions return { id, status: “queued” }. If a widget is visible, it polls the status action automatically — do not re-invoke get_* as a follow-up poll. In text-only clients, poll by invoking the app’s status action (e.g. get_render) until status is completed/failed. The action’s own annotations (from apps_describe) indicate cost/side-effects; confirm with the user before an expensive or destructive action.

Input Parameters

string
required
Action name from apps_describe.
string
required
App UUID from apps_search.
object
Action arguments matching its input_schema. Do not put binary/media bytes here — pass a media_id.
string
required
From apps_describe. If it changed since, the call is rejected with manifest_changed — re-describe.

Output

object
App-specific result; its shape is the action’s output_schema.
string
string
string
boolean
string
string
string
string
Slug: HIGGSFIELD_MCP_APPS_SEARCHSearch Higgsfield Marketplace apps callable through MCP. Returns each app’s id, name, and the actions it exposes. Flow: apps_search to find an app → apps_describe(app_id, action) to get an action’s argument schema + manifest_revision → apps_invoke to run it. Read-only; does not call any app.

Input Parameters

integer
Max results (default 20).
string
Case-insensitive substring over app name/description. Omit to list all.
string
Opaque pagination cursor from a previous next_cursor.

Output

string
array
boolean
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Slug: HIGGSFIELD_MCP_BALANCEGet the user’s available credits and current subscription plan. For transaction history, call transactions instead.

Output

string
Error message if balance could not be fetched
number
Available credits
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Current subscription plan
Slug: HIGGSFIELD_MCP_CANCEL_TRIAL_AUTO_RENEWALCancel the auto-renewal of the Higgsfield MCP free trial. Call this when the user asks to cancel the trial, cancel auto-renewal, stop the upcoming charge, or asks how to cancel. IMPORTANT SEMANTICS: cancelling stops the automatic charge at the end of the trial ONLY — the user KEEPS trial access and remaining trial credits until the trial ends; nothing is charged. First call WITHOUT confirm (or confirm=false): in UI clients this opens a confirmation card with ‘Keep trial with auto-renewal’ and ‘Cancel auto-renewal’ buttons; in text-only clients relay assistant_response verbatim and wait for the user’s explicit confirmation. Only call again with confirm=true after the user explicitly confirmed the cancellation in chat. Never pass confirm=true on the first call.

Input Parameters

boolean
false (default): show the cancellation confirmation (widget in UI clients, question in text clients) — always start here. true: actually cancel auto-renewal — pass ONLY after the user explicitly confirmed the cancellation in chat (text-only clients; in UI clients the widget button confirms).

Output

string
string
ISO currency code for then_price_cents; absent means USD.
boolean
True when auto-renewal was cancelled by this call (confirm=true path).
string
MCP server HTTP request ID for support/debugging.
string ("cancel_trial")
Tells the plans widget to render the cancel-confirmation card.
object
Current trial state backing the confirmation copy.
number
Price that would be auto-charged after the trial, in cents.
string
Ready-to-send response. Relay verbatim in text-only clients.
boolean
Presentation-only gate derived from the existing trial’s kind. False/absent keeps the legacy cancellation copy.
Slug: HIGGSFIELD_MCP_CONFIRM_BILLING_PURCHASEINTERNAL — invoked ONLY by the plans widget on an explicit user Confirm click. Do NOT call this tool yourself; it charges the user’s real saved payment method off-session. To help a user upgrade, top up, or set auto top-up, call show_plans_and_credits instead — it returns checkout links and, in UI clients, opens the widget where the user confirms the charge. Covers auto_topup and topup via the action field (upgrade_plan is temporarily disabled — plan upgrades use the hosted checkout link). The backend either charges the saved card (result: "charged") or returns a checkout_url to redirect (result: "redirect"). Buying a brand-new subscription is not handled here — that uses the hosted checkout link.

Input Parameters

string ("upgrade_plan" | "auto_topup" | "topup")
required
Billing action the user confirmed: upgrade_plan (needs plan_id+billing_period), topup (needs topup_id), auto_topup (enabled + top_up_amount_cents, or enabled:false to disable).
boolean
Enable (true, default) or disable (false) auto top-up (auto_topup).
string ("plus" | "ultra")
Target plan tier (upgrade_plan).
string
McpCreditTopupCard.id of the selected pack (topup).
string ("monthly" | "annual")
Target billing cadence (upgrade_plan).
integer
Auto top-up amount in cents (dollar amount) — one of auto_refill.options (auto_topup, when enabling).

Output

string
string ("upgrade_plan" | "auto_topup" | "topup")
Echo of the confirmed action.
string ("charged" | "redirect" | "error")
Discriminant. ‘charged’ = the operation succeeded (card charged or setting saved) — show success + close modal. ‘redirect’ = open checkout_url. ‘error’ = show error.
number
Credits added by a top-up.
string
ISO currency code (usd/eur/gbp) for the monetary fields in this response; absent means USD.
object
Resulting plan after an upgrade (tier, billing_period, credits_per_month, price_per_seat).
string
MCP server HTTP request ID for support/debugging.
number
Top-up price charged, in cents.
string
Set by the shared error path on plan-required / out-of-credits errors.
string
Hosted checkout/invoice URL when the charge could not complete off-session. Widget opens it; text clients relay it as a link.
number
Total to pay, in cents (upgrade_plan).
string
CTA label for checkout_url.
string
Ready-to-show confirmation copy.
boolean
number
Prorated amount charged today, in cents (upgrade_plan).
number
Credits granted by the upgrade (upgrade_plan).
Slug: HIGGSFIELD_MCP_CONFIRM_TRIAL_CANCELINTERNAL — invoked ONLY by the cancel-trial confirmation widget on an explicit user click of ‘Cancel auto-renewal’. Do NOT call this tool yourself; to cancel the trial’s auto-renewal use cancel_trial_auto_renewal instead. Stops the trial’s auto-renewal (cancel_at_period_end) — trial access and remaining credits stay until the trial ends.

Output

string
string ("cancelled" | "error")
Discriminant for the widget.
string
MCP server HTTP request ID for support/debugging.
string
Ready-to-show confirmation copy.
Slug: HIGGSFIELD_MCP_CREATE_VOICEOpen the Create Voice Apps UI. Call this immediately when the user asks to create a voice, call the Create Voice tool, or needs a local browser record/upload surface and no confirmed audio_media_id is already present. Do not ask the user to upload an audio file or provide the name in chat first; the widget collects the required name plus record/upload audio. If the user already has or attached an audio file in chat, still call this tool with initial_tab=‘upload’ — remote tools cannot read Claude chat attachments, so the user re-selects the file in the widget’s Upload tab (it uploads directly to Higgsfield). Do not try to pass a chat attachment or ask for a URL. The widget records/uploads, confirms the audio, and creates the voice itself end-to-end — and if the user is out of credits or on a free plan it shows the plans/credits UI inline. After the widget reports success you do NOT need to call create_voice_from_confirmed_audio again. Only call create_voice_from_confirmed_audio yourself when a confirmed audio_media_id is already present in the prompt and no UI step is needed.

Input Parameters

string
Initial name to prefill in the UI.
string ("record" | "upload")
Initial tab for the create voice UI. Defaults to record. Use ‘upload’ when the user already has or attached an audio file.

Output

string
required
Discriminator for the widget’s initial view.
string
Initial name to prefill in the UI.
object
required
string ("record" | "upload")
required
Initial tab for the create voice UI.
string
required
URI of the UI resource this tool binds to.
boolean
required
True when the record tab may request browser microphone permission.
Slug: HIGGSFIELD_MCP_CREATE_VOICE_FROM_CONFIRMED_AUDIOBackend-only creation of a cloned voice from an already confirmed audio upload. Do not call this tool until audio_media_id and name are already known. For direct creation, first upload speech audio with media_upload, PUT the bytes, then call media_confirm with type=‘audio’. Pass that confirmed media_id here as audio_media_id plus a required name. If the user needs to record or upload local audio in an Apps UI-capable client, call create_voice instead; that widget records/uploads, confirms, and creates the voice itself, so you do not call this tool for the UI flow. The audio should be clear speech, roughly 10 seconds to 3 minutes, and no larger than the upload limit. The backend charges the voice-clone credit cost on successful creation. Cloning is asynchronous: on success the tool returns the new voice_id plus a status, and a fresh clone is usually still ‘processing’ and not yet usable. Use the returned voice_id with voice_type=‘element’ for generate_audio or voice_change only once it is ready (status=‘completed’ and is_audio_eligible=true). If status is ‘processing’ or is_audio_eligible is not true, the clone is still training — re-check it with list_voices before generating instead of submitting right away; status ‘voice_clone_failed’/‘failed’ means cloning did not succeed. If recovery_tool is returned, call it immediately; do not explain/ask first.

Input Parameters

string
required
Required display name for the created voice.
string
Optional voice description for backend metadata.
string
required
Confirmed audio media_id from media_confirm(type=‘audio’).

Output

string
Error message if the voice could not be created.
object
Created voice. Use voice_id with voice_type=‘element’ once status=‘completed’ and is_audio_eligible=true.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Direct URL for the primary checkout/setup action. Agents MUST show this exact link in text-only clients.
string ("show_plans_and_credits" | "media_import_url")
Canonical recovery tool for host/client routing.
string
CTA label for checkout_url.
All direct purchase/setup links returned for billing recovery.
string
Personalized seller-style headline for the recovery offer.
string
Short reason for opening the recovery tool.
string
Action-oriented CTA label for the primary recovery link.
string
Short promoter-style recovery copy.
string
Ready-to-send promoter-style billing response. Generation tools prefer recovery_tool instead; billing tools use this for final sales copy with checkout URLs formatted as action-specific Markdown links, e.g. Go to Checkout, Higgsfield Upgrade, Higgsfield Credit Top-up, or Higgsfield Auto-refill.
string
Arguments for the recovery tool.
string ("upgrade" | "topup" | "auto_refill" | "trial" | "general")
Purchase path selected for this recovery response.
Direct subscription upgrade links.
Direct one-time credit-pack links.
Best single checkout/setup link for this recovery path. Out-of-credits recovery prioritizes auto-refill when eligible, then one-time top-ups.
string
Short rationale for why this recovery offer is being shown.
object
Context for media import recovery before retrying a generation.
object
Optional context explaining why the billing recovery response was attached.
Direct auto-refill setup link.
Slug: HIGGSFIELD_MCP_CREATE_WEBSITEStart a new full-stack website. Creates the website and a git repo: a React 19 + TanStack Start app, server-rendered, in ONE Cloudflare Worker, with D1 / R2 / KV / Durable Objects / Containers available (all DISABLED by default). Returns a website_id — pass it to every later website tool. The ‘type’ param is REQUIRED and is the USER’S choice, not yours: unless the user has already made it unambiguous, ASK the user whether they want a plain website (no Higgsfield integration) or a Higgsfield-integrated app (Sign in with Higgsfield + AI image/video generation via the Higgsfield SDK) BEFORE calling this tool. Apps are scaffolded from a v2 starter template and REQUIRE the ‘template’ param — pick the closest of studio / preset / app-detail per the template param’s guide (‘custom’ is ONLY for when the user explicitly says “use custom template” — never pick it yourself). The chosen layout ships as real code already wired as the home page; you ADAPT IT IN PLACE, never rebuild it. Websites take an OPTIONAL template: pass ‘scroll-scrub’ for an animated website (its scrub engine ships pre-built) and omit it for a non-animated one. App and website templates are not interchangeable — a cross-kind name is rejected. Workflow: (0) call get_workflow_instructions with { workflow: “website-builder-flow” } FIRST to load the stack, design contract, and hard rules (REQUIRED before building or editing); (1) create_website; (2) call website_repo_access to get the repo’s git URL + scoped token, clone/edit/commit/push with the terminal (for apps, read app/src/layouts/AGENTS.md + app/src/components/AGENTS.md right after cloning); (3) deploy_website to ship it live — and deploy again after ANY later change (publish_website only lists what is already live; it does not deploy).

Input Parameters

string ("website" | "app" | "game")
required
REQUIRED — what the user chose to build. ‘website’: a standalone site with NO Higgsfield integration (no Sign in with Higgsfield, no requests to Higgsfield). ‘app’: a product tightly integrated with Higgsfield — its users sign in with Higgsfield and generate images/videos through the Higgsfield SDK. ‘game’: a browser game with realtime multiplayer rooms — requires a game genre as category and takes NO template. This is the user’s decision: if their request doesn’t make it obvious, ask them which one they want before creating.
string
required
REQUIRED — the content category the website is filed under, a slug from the marketplace taxonomy (e.g. ‘cinematic’, ‘ads-marketing’, ‘ugc-social’, ‘other’). Call list_website_categories to get the exact valid slugs, then pass the closest one (‘other’ when nothing fits). The server rejects an unknown slug.
string ("app-detail" | "preset" | "studio" | "custom" | "scroll-scrub")
The starter template the repo is scaffolded from. Its code arrives already wired as the home page — you adapt it in place, not rebuild it. The valid names depend on type, and a mismatch is rejected. type=‘website’ — OPTIONAL: ‘scroll-scrub’ = the animated website (the visitor’s scroll plays a generated film); its scrub engine ships pre-built, so you generate the film and fill in scenes instead of writing a controller. Pass it for EVERY animated website (the default per the website-builder flow). OMIT template only for a non-animated site. Never pass an app template for a website. type=‘app’ — REQUIRED, pick the closest to the product: ‘studio’ = full creative workspace (projects sidebar + floating prompt dock + edge-to-edge generations feed) for multi-project generation tools; ‘preset’ = pick-a-style-then-generate (persistent left creation rail beside a browsable preset grid with History tab); ‘app-detail’ = a single tool’s landing page (two-column generator hero + how-it-works steps) — the ‘simple app’. Any other request shape (before/after slider, step-by-step wizard, upload-configure-iterate) still maps to the closest of these three; the shared components in app/src/components/ cover those patterns. ‘custom’ (bare shell, no shipped layout) is ONLY for when the user explicitly says “use custom template” — never pick it yourself.
string
The website’s subdomain — it becomes the slug, so the live URL is <subdomain>.<host>. ALWAYS set this: pick a short, memorable subdomain from the site’s name or purpose (lowercase letters, digits, and single hyphens only; DNS-safe). Only omit it — which falls back to a random subdomain — if the user explicitly asks for a random one. A few reserved labels (e.g. ‘api’, ‘www’) and already-taken subdomains are rejected; if that happens, try a close variant.

Output

string
string
URL slug (also the repo name).
string
The product kind that was created: ‘website’ or ‘app’.
string
string
The starter template the site was scaffolded from.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
The new website’s id. Remember it.
Slug: HIGGSFIELD_MCP_DEPLOY_WEBSITEBuild and deploy the website via CI, then return its live URL. Every deploy ships the live site at the website’s public URL (there is no separate preview stage). IMPORTANT: commit and git push ALL your changes BEFORE calling this — the build runs from the pushed repo. Deploy again after ANY later change: publish_website does NOT deploy (it only lists the already-live build on the community feed), so this tool is the only way changes ship. A failed build returns the log; a still-running build returns status ‘pending’ — call website_status to check.

Input Parameters

string
required
The website’s id (returned by create_website).

Output

string
string
The deployed site’s title (from its og:title / <title>).
string
Build log when the deploy failed.
string
deployed / failed / pending
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Echo of the input id — the widget’s publish/contest buttons need it.
string
The deployed site’s favicon URL.
string
The deployed site’s OG banner image URL.
Slug: HIGGSFIELD_MCP_DUBBINGDub a video into another language: translate the spoken audio, synthesize it in the target language, and lip-sync the result back onto the video. Use this when the user asks to dub, translate the speech of, or localize a clip into another language. Pass video_id for the source video (a confirmed uploaded media_id or a completed video generation job_id) and target_language as one of the supported language codes. Supported languages (code=language): eng=English, cmn=Chinese, fra=French, hin=Hindi, ita=Italian, jpn=Japanese, kor=Korean, por=Portuguese, rus=Russian, tur=Turkish, spa=Spanish, deu=German, ara=Arabic, pol=Polish, ind=Indonesian, fil=Filipino, swe=Swedish, fin=Finnish. This tool does not use prompt or count; output dimensions are taken from the source video automatically.

Input Parameters

object
required
Dubbing parameters.

Output

object
Populated only when the tool was called with get_cost: true. No job was submitted.
string
object
array
string
object
Suggested follow-up tool call (e.g. show_marketing_studio fetch) attached to some marketing error results.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
object
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Direct URL for the primary checkout/setup action. Agents MUST show this exact link in text-only clients.
object
NO JOB WAS SUBMITTED. The caller has free unlimited generations that cover this model, and nobody has said whether to spend them. Ask the user, then call the same tool again with use_unlim: true (free) or use_unlim: false (credits). Do not pick for them.
string ("show_plans_and_credits" | "media_import_url")
Canonical recovery tool for host/client routing.
string
CTA label for checkout_url.
All direct purchase/setup links returned for billing recovery.
string
Personalized seller-style headline for the recovery offer.
string
Short reason for opening the recovery tool.
string
Live brand kit status when a generation was rejected because the kit is not ready yet.
string
Action-oriented CTA label for the primary recovery link.
string
Short promoter-style recovery copy.
string
Ready-to-send promoter-style billing response. Generation tools prefer recovery_tool instead; billing tools use this for final sales copy with checkout URLs formatted as action-specific Markdown links, e.g. Go to Checkout, Higgsfield Upgrade, Higgsfield Credit Top-up, or Higgsfield Auto-refill.
object
Set when the server auto-picked an avatar because product_ids were passed without avatars/avatar_ids (Marketing Studio video).
string
Arguments for the recovery tool.
string ("upgrade" | "topup" | "auto_refill" | "trial" | "general")
Purchase path selected for this recovery response.
Direct subscription upgrade links.
Direct one-time credit-pack links.
Best single checkout/setup link for this recovery path. Out-of-credits recovery prioritizes auto-refill when eligible, then one-time top-ups.
string
Short rationale for why this recovery offer is being shown.
object
Context for media import recovery before retrying a generation.
object
Optional context explaining why the billing recovery response was attached.
Direct auto-refill setup link.
Slug: HIGGSFIELD_MCP_GENERATE_3DGenerate a 3D GLB mesh. Use models_explore(type:'3d') to pick a model and see its medias[].roles and parameters. Apps UI local file: call media_upload_widget; remote tools cannot read Claude chat attachments. Web media URL: call media_import_url, pass returned media_id; medias[].value must be media_id/job_id, not URL. Defaults: image_to_3d for general image-to-3D with optional texturing, PBR, and rigging; multi_image_to_3d when 2-4 views of the same subject are available (better geometric accuracy); sam_3_3d for single-object reconstruction; 3d_rigging to rig an existing 3D model (takes model_url, not images — pass a prior 3D job_id or an https GLB URL). For animated rigs, search clip ids with the animation_actions tool and pass animation_action_id with enable_animation:true. The mesh reproduces only what is in the source image — to add or change props, clothing, or held objects, edit the image first with generate_image, then convert the edited result. Pass model-specific params as top-level fields. Apply adjustments returned by the server. If recovery_tool is returned, call it immediately. get_cost:true preflights credits without submitting.

Input Parameters

string
required

Output

object
Populated only when the tool was called with get_cost: true. No job was submitted.
string
object
array
string
object
Suggested follow-up tool call (e.g. show_marketing_studio fetch) attached to some marketing error results.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
object
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Direct URL for the primary checkout/setup action. Agents MUST show this exact link in text-only clients.
object
NO JOB WAS SUBMITTED. The caller has free unlimited generations that cover this model, and nobody has said whether to spend them. Ask the user, then call the same tool again with use_unlim: true (free) or use_unlim: false (credits). Do not pick for them.
string ("show_plans_and_credits" | "media_import_url")
Canonical recovery tool for host/client routing.
string
CTA label for checkout_url.
All direct purchase/setup links returned for billing recovery.
string
Personalized seller-style headline for the recovery offer.
string
Short reason for opening the recovery tool.
string
Live brand kit status when a generation was rejected because the kit is not ready yet.
string
Action-oriented CTA label for the primary recovery link.
string
Short promoter-style recovery copy.
string
Ready-to-send promoter-style billing response. Generation tools prefer recovery_tool instead; billing tools use this for final sales copy with checkout URLs formatted as action-specific Markdown links, e.g. Go to Checkout, Higgsfield Upgrade, Higgsfield Credit Top-up, or Higgsfield Auto-refill.
object
Set when the server auto-picked an avatar because product_ids were passed without avatars/avatar_ids (Marketing Studio video).
string
Arguments for the recovery tool.
string ("upgrade" | "topup" | "auto_refill" | "trial" | "general")
Purchase path selected for this recovery response.
Direct subscription upgrade links.
Direct one-time credit-pack links.
Best single checkout/setup link for this recovery path. Out-of-credits recovery prioritizes auto-refill when eligible, then one-time top-ups.
string
Short rationale for why this recovery offer is being shown.
object
Context for media import recovery before retrying a generation.
object
Optional context explaining why the billing recovery response was attached.
Direct auto-refill setup link.
Slug: HIGGSFIELD_MCP_GENERATE_AUDIOGenerate one speech/voice request (text-to-speech) and render it in the generation widget. This tool accepts one prompt; for 2-12 independent lines or prompts, use the headless generate_audio_batch tool instead. DEFAULT model: seed_audio (Seed Audio 1.0 by ByteDance) — use it unless the user explicitly asks for a different engine. seed_audio takes a preset or reference-element voice (voice_type ‘preset’|‘element’ + voice_id) plus optional tuning params (format, sample_rate, speech_rate, loudness_rate, pitch_rate), and can clone a voice from an audio_references media item or take an image_references cue. To use a specific named engine instead, set model:‘text2speech_v2’ and pass variant (one of elevenlabs|minimax|seed_speech|vibe_voice|cozy_voice) together with voice_type + voice_id. Get voice ids from list_voices; use models_explore(type:‘audio’) to inspect each model’s params. This tool only generates speech: it cannot generate music or sound effects for general use, and there is no standalone music/SFX model here — decline general music or sound-effect requests rather than substituting a speech model. The models sonilo_music (music), mirelo_text_to_audio (sound effects) and inworld_text_to_speech (voice) exist ONLY for the game-generation pipeline and must not be used for standalone audio. get_cost:true preflights credits without submitting. use_unlim defaults false — pass true only when the user explicitly asks to use their unlimited/free-trial generations, never to save them credits on your own initiative.

Input Parameters

string
required

Output

object
Populated only when the tool was called with get_cost: true. No job was submitted.
string
object
array
string
object
Suggested follow-up tool call (e.g. show_marketing_studio fetch) attached to some marketing error results.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
object
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Direct URL for the primary checkout/setup action. Agents MUST show this exact link in text-only clients.
object
NO JOB WAS SUBMITTED. The caller has free unlimited generations that cover this model, and nobody has said whether to spend them. Ask the user, then call the same tool again with use_unlim: true (free) or use_unlim: false (credits). Do not pick for them.
string ("show_plans_and_credits" | "media_import_url")
Canonical recovery tool for host/client routing.
string
CTA label for checkout_url.
All direct purchase/setup links returned for billing recovery.
string
Personalized seller-style headline for the recovery offer.
string
Short reason for opening the recovery tool.
string
Live brand kit status when a generation was rejected because the kit is not ready yet.
string
Action-oriented CTA label for the primary recovery link.
string
Short promoter-style recovery copy.
string
Ready-to-send promoter-style billing response. Generation tools prefer recovery_tool instead; billing tools use this for final sales copy with checkout URLs formatted as action-specific Markdown links, e.g. Go to Checkout, Higgsfield Upgrade, Higgsfield Credit Top-up, or Higgsfield Auto-refill.
object
Set when the server auto-picked an avatar because product_ids were passed without avatars/avatar_ids (Marketing Studio video).
string
Arguments for the recovery tool.
string ("upgrade" | "topup" | "auto_refill" | "trial" | "general")
Purchase path selected for this recovery response.
Direct subscription upgrade links.
Direct one-time credit-pack links.
Best single checkout/setup link for this recovery path. Out-of-credits recovery prioritizes auto-refill when eligible, then one-time top-ups.
string
Short rationale for why this recovery offer is being shown.
object
Context for media import recovery before retrying a generation.
object
Optional context explaining why the billing recovery response was attached.
Direct auto-refill setup link.
Slug: HIGGSFIELD_MCP_GENERATE_AUDIO_BATCHSubmit 1-12 independent audio generations in parallel without opening a widget. Each requests[] item accepts the same params as generate_audio, creates exactly one job, and keeps its caller-provided index in the response. Use for multiple distinct prompts or inputs; use generate_audio for one user-facing generation. Poll returned job IDs with jobs_wait in agent-chosen groups of at most 12. For larger sets, collect indexed jobs across submission batches. After every job in the user’s set is terminal, pass the collected jobs to exactly one show_generation_by_ids call for up to 60 jobs; never use show_generations or call job_display once per job.

Input Parameters

array
required
Ordered audio generation requests. Response jobs keep the provided indices.

Output

array
required
integer
required
integer
required
Slug: HIGGSFIELD_MCP_GENERATE_IMAGEGenerate one image request and render its result(s) in the generation widget. Use count 2-4 only for variants of the same prompt, inputs, and settings; for 2-12 independent image requests with different prompts or inputs, use the headless generate_image_batch tool instead. Apps UI local file media: call media_upload_widget; do not ask for Claude chat attachments because remote tools cannot read them. Web media URL: call media_import_url, then pass returned media_id; medias[].value must be media_id/job_id, not URL. Default general image model: gpt_image_2 — use it for ordinary generation, photorealistic images, typography, and reference-based editing unless a specialized route applies. Specialized defaults: marketing_studio_image for commercial/product/ads; soul_cast for text-only character/avatar; soul_2+soul_id for trained reusable Soul; soul_2 for portraits/fashion/UGC/editorial. Ambiguous create-character/avatar: offer reusable Soul training (5-20 photos, ~10 min) vs one-off; do not train generic silently. Use show_characters(action='train') only if explicitly requested or user provides 5-20 photos. Use models_explore for aspect_ratios, params, medias roles. Top-level model params; apply adjustments. If recovery_tool returned, call it immediately; do not explain/ask first. get_cost:true preflights credits. use_unlim defaults false — pass true only when the user explicitly asks to use their unlimited/free-trial generations, never to save them credits on your own initiative.

Input Parameters

string
required

Output

object
Populated only when the tool was called with get_cost: true. No job was submitted.
string
object
array
string
object
Suggested follow-up tool call (e.g. show_marketing_studio fetch) attached to some marketing error results.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
object
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Direct URL for the primary checkout/setup action. Agents MUST show this exact link in text-only clients.
object
NO JOB WAS SUBMITTED. The caller has free unlimited generations that cover this model, and nobody has said whether to spend them. Ask the user, then call the same tool again with use_unlim: true (free) or use_unlim: false (credits). Do not pick for them.
string ("show_plans_and_credits" | "media_import_url")
Canonical recovery tool for host/client routing.
string
CTA label for checkout_url.
All direct purchase/setup links returned for billing recovery.
string
Personalized seller-style headline for the recovery offer.
string
Short reason for opening the recovery tool.
string
Live brand kit status when a generation was rejected because the kit is not ready yet.
string
Action-oriented CTA label for the primary recovery link.
string
Short promoter-style recovery copy.
string
Ready-to-send promoter-style billing response. Generation tools prefer recovery_tool instead; billing tools use this for final sales copy with checkout URLs formatted as action-specific Markdown links, e.g. Go to Checkout, Higgsfield Upgrade, Higgsfield Credit Top-up, or Higgsfield Auto-refill.
object
Set when the server auto-picked an avatar because product_ids were passed without avatars/avatar_ids (Marketing Studio video).
string
Arguments for the recovery tool.
string ("upgrade" | "topup" | "auto_refill" | "trial" | "general")
Purchase path selected for this recovery response.
Direct subscription upgrade links.
Direct one-time credit-pack links.
Best single checkout/setup link for this recovery path. Out-of-credits recovery prioritizes auto-refill when eligible, then one-time top-ups.
string
Short rationale for why this recovery offer is being shown.
object
Context for media import recovery before retrying a generation.
object
Optional context explaining why the billing recovery response was attached.
Direct auto-refill setup link.
Slug: HIGGSFIELD_MCP_GENERATE_IMAGE_BATCHSubmit 1-12 independent image generations in parallel without opening a widget. Each requests[] item accepts the same params as generate_image, creates exactly one job, and keeps its caller-provided index in the response. Use for multiple distinct prompts or inputs; use generate_image for one user-facing generation. Poll returned job IDs with jobs_wait in agent-chosen groups of at most 12. For larger sets, collect indexed jobs across submission batches. After every job in the user’s set is terminal, pass the collected jobs to exactly one show_generation_by_ids call for up to 60 jobs; never use show_generations or call job_display once per job.

Input Parameters

array
required
Ordered image generation requests. Response jobs keep the provided indices.

Output

array
required
integer
required
integer
required
Slug: HIGGSFIELD_MCP_GENERATE_VIDEOGenerate one direct video request and render it in the generation widget. Use count 2-4 only for variants of the same prompt, inputs, and settings; use headless generate_video_batch for 2-12 independent requests. GENJUTSU TRIGGERS: route Higgsfield Genjutsu by intent. Copy, repeat, reproduce, mimic, or transfer motion, movement, actions, gestures, dance, or camera motion from one driving video to reference-image subjects -> hf_mult_motion_control. Replace, change, or swap an object, product, garment, or character in one source video from reference images -> hf_mult_replace_object. These are direct generate_video models, not legacy motion_control or ad-multiplier; reserve ad-multiplier for explicitly requested independent variants. Pass images with role image and exactly one source/driving video with role video. LOCAL/ATTACHED INPUT GATE: without confirmed media_id values, call media_upload_widget first as the only tool in that turn; never inspect /mnt/user-data/uploads, run shell, or ask for a chat attachment. For mixed image+video use type:auto, multiple:true. For web media call media_import_url; medias[].value must be media_id/job_id. Defaults: marketing_studio_video for ads/products, clipify for YouTube clips, seedance_2_5 for general video, kling3_0 for multi-shot, audio, or motion transfer, and minimax_h3 for 2K keyframes or mixed references. Marketing Studio: fetch URL products with show_marketing_studio(action='fetch'); create uploaded-image products with type product. List missing hooks/settings before presets. Use declared media roles and model-supported audio only. Use models_explore for durations/params. Apply adjustments and immediately call any recovery_tool. get_cost:true preflights credits. Set use_unlim:true only when explicitly requested.

Input Parameters

string
required

Output

object
Populated only when the tool was called with get_cost: true. No job was submitted.
string
object
array
string
object
Suggested follow-up tool call (e.g. show_marketing_studio fetch) attached to some marketing error results.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
object
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Direct URL for the primary checkout/setup action. Agents MUST show this exact link in text-only clients.
object
NO JOB WAS SUBMITTED. The caller has free unlimited generations that cover this model, and nobody has said whether to spend them. Ask the user, then call the same tool again with use_unlim: true (free) or use_unlim: false (credits). Do not pick for them.
string ("show_plans_and_credits" | "media_import_url")
Canonical recovery tool for host/client routing.
string
CTA label for checkout_url.
All direct purchase/setup links returned for billing recovery.
string
Personalized seller-style headline for the recovery offer.
string
Short reason for opening the recovery tool.
string
Live brand kit status when a generation was rejected because the kit is not ready yet.
string
Action-oriented CTA label for the primary recovery link.
string
Short promoter-style recovery copy.
string
Ready-to-send promoter-style billing response. Generation tools prefer recovery_tool instead; billing tools use this for final sales copy with checkout URLs formatted as action-specific Markdown links, e.g. Go to Checkout, Higgsfield Upgrade, Higgsfield Credit Top-up, or Higgsfield Auto-refill.
object
Set when the server auto-picked an avatar because product_ids were passed without avatars/avatar_ids (Marketing Studio video).
string
Arguments for the recovery tool.
string ("upgrade" | "topup" | "auto_refill" | "trial" | "general")
Purchase path selected for this recovery response.
Direct subscription upgrade links.
Direct one-time credit-pack links.
Best single checkout/setup link for this recovery path. Out-of-credits recovery prioritizes auto-refill when eligible, then one-time top-ups.
string
Short rationale for why this recovery offer is being shown.
object
Context for media import recovery before retrying a generation.
object
Optional context explaining why the billing recovery response was attached.
Direct auto-refill setup link.
Slug: HIGGSFIELD_MCP_GENERATE_VIDEO_BATCHSubmit 1-12 independent video generations in parallel without opening a widget. Each requests[] item accepts the same params as generate_video, creates exactly one job, and keeps its caller-provided index in the response. Use for multiple distinct prompts or inputs; use generate_video for one user-facing generation. Poll returned job IDs with jobs_wait in agent-chosen groups of at most 12. For larger sets, collect indexed jobs across submission batches. After every job in the user’s set is terminal, pass the collected jobs to exactly one show_generation_by_ids call for up to 60 jobs; never use show_generations or call job_display once per job.

Input Parameters

array
required
Ordered video generation requests. Response jobs keep the provided indices.

Output

array
required
integer
required
integer
required
Slug: HIGGSFIELD_MCP_GET_EXPLAINER_PRESETSShow the explainer video style presets (CMS-managed catalog). Returns preset ids, names, and preview media. When the user picks one, resolve it with resolve_explainer_preset to get the style reference media_id for generations.

Output

string
Set when the preset catalog could not be loaded.
array
required
Slug: HIGGSFIELD_MCP_GET_WORKFLOW_BUNDLE_FILERead a safe text file or directory from a workflow’s resource folder. Use this after get_workflow_instructions when the SKILL.md requires a template, reference, or script file.

Input Parameters

string
required
Whitelisted path INSIDE that workflow folder, e.g. ‘references/prompts.md’ or ‘scripts/assemble_blocks.sh’.
string
required
Workflow name whose folder holds the file, e.g. ‘faceless-video’.
boolean
For directory paths, include the content of every allowed file under that directory. Defaults to false.

Output

string ("file" | "directory" | "error")
required
Whether the response is a single file, directory listing, or error.
string
required
Normalized path inside the workflow folder.
string
Error message for error responses.
array
Recursive file contents when include_contents is true for a directory.
string
File content for file responses.
array
Direct child entries for directory responses.
string
required
Workflow name.
string
MIME type for file responses.
integer
Number of files included or available in a directory response.
integer
File size for file responses.
integer
Total bytes included or available in a directory response.
integer
Maximum allowed single file size.
integer
Maximum allowed directory content size.
Slug: HIGGSFIELD_MCP_GET_WORKFLOW_INSTRUCTIONSAd Multiplier — load workflow ‘ad-multiplier’ when the user asks to ‘multiply my video’, ‘multiply my ad’, create multiple independently edited versions of one supplied 4-30 second video, or regenerate the same ad with different people or products. Load this workflow before Marketing Studio, model browsing, or direct generation. Brand Asset Creation: for branded-asset work including logo recoloring/export, a branded PowerPoint/presentation deck, or analyzing an official brandbook to produce an asset, even when all inputs are supplied or no generation is needed, load ‘brand-asset-creation’ before sandbox_exec. Faceless video generation, AI-narrated video, narrated animated explainer video, narrated / personal / philosophical story video, YouTube/Instagram thumbnail or video cover, product photoshoot, packshot, studio or lifestyle product photography, product hero banner, product carousel, static product ad pack, virtual model product try-on, conceptual product still, or product-photo restyle, UGC-style ad for a website / SaaS / store / product page from its URL (‘SaaS UGC’), any other UGC / creator-style short video for a product — a talking-head creator review (the default UGC ask), a product-only ad with no creator on camera, an unboxing / first-reaction / haul, a try-on / fit check / OOTD, a step-by-step tutorial with on-screen steps, a character sheet, character reference, model sheet, turnaround, expression sheet, or consistent multi-view character prompt, any branding work — a logo, visual identity, brand kit, brandbook, branded mockups, merchandise, packaging, signage, social graphics, posters, or banners (‘brand-asset-creation’), including recoloring or exporting an existing official SVG/PNG logo even when no new design or image generation is requested, or building / editing a website, web app, landing page, or browser game with the website tools (‘website-builder-flow’): before building ANY of these, use this tool to discover and load the bundled workflow (each a SKILL.md that orchestrates the generate_* tools). Call with NO argument to list available workflows and their triggers. Call with a workflow name to load that workflow’s full SKILL.md plus the list of files readable via get_workflow_bundle_file.

Input Parameters

string
Workflow name (a folder under the workflows resource root, e.g. ‘faceless-video’). Omit to list all available workflows.

Output

string ("catalog" | "workflow" | "error")
required
Whether the response lists workflows or loads one.
string
Error message if the request could not be served.
string
required
Where the content came from.
string
Workflow version from SKILL.md frontmatter, if present.
string
Loaded workflow name (workflow mode).
array
Available workflows (catalog mode).
string
Sandbox directory where this workflow’s bundled scripts are already installed (its scripts/ lives here). Absent when the workflow bundles none.
array
Files readable with get_workflow_bundle_file.
string
How to load detailed resource files.
array
Directories readable with get_workflow_bundle_file.
string
The workflow’s SKILL.md entrypoint (workflow mode).
Slug: HIGGSFIELD_MCP_JOB_DISPLAYShow one specific previous generation in the single-result UI widget by job ID. Use when the user wants to inspect or re-display that individual result, including workflows that require separate approval of named candidates or individual previews before finalization. Do not call job_display once per job merely to reproduce an ordinary completed batch; use one show_generation_by_ids call for ordinary batch results instead.

Input Parameters

string
required
Job ID to display

Output

string
array
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Direct URL for the primary checkout/setup action. Agents MUST show this exact link in text-only clients.
string ("show_plans_and_credits" | "media_import_url")
Canonical recovery tool for host/client routing.
string
CTA label for checkout_url.
All direct purchase/setup links returned for billing recovery.
string
Personalized seller-style headline for the recovery offer.
string
Short reason for opening the recovery tool.
string
Action-oriented CTA label for the primary recovery link.
string
Short promoter-style recovery copy.
string
Ready-to-send promoter-style billing response. Generation tools prefer recovery_tool instead; billing tools use this for final sales copy with checkout URLs formatted as action-specific Markdown links, e.g. Go to Checkout, Higgsfield Upgrade, Higgsfield Credit Top-up, or Higgsfield Auto-refill.
string
Arguments for the recovery tool.
string ("upgrade" | "topup" | "auto_refill" | "trial" | "general")
Purchase path selected for this recovery response.
Direct subscription upgrade links.
Direct one-time credit-pack links.
Best single checkout/setup link for this recovery path. Out-of-credits recovery prioritizes auto-refill when eligible, then one-time top-ups.
string
Short rationale for why this recovery offer is being shown.
object
Context for media import recovery before retrying a generation.
object
Optional context explaining why the billing recovery response was attached.
Direct auto-refill setup link.
Slug: HIGGSFIELD_MCP_JOB_STATUSCheck the status and results of an async job. Returns instantly. For non-terminal jobs the response includes poll_after_seconds — wait that many seconds before calling again. Typical total times: image ~10-20s, video ~60-180s.

Input Parameters

boolean
If true, server polls internally for up to ~25s and returns on terminal state. Defaults to false.
string
required
Job ID from a previous operation
string
Set by the generation widget when it polls automatically.
boolean
If true, return the raw FNF job payload instead of the normalized generation shape.

Output

string
string
number
boolean
object
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Direct URL for the primary checkout/setup action. Agents MUST show this exact link in text-only clients.
string ("show_plans_and_credits" | "media_import_url")
Canonical recovery tool for host/client routing.
string
CTA label for checkout_url.
All direct purchase/setup links returned for billing recovery.
string
Personalized seller-style headline for the recovery offer.
string
Short reason for opening the recovery tool.
string
Action-oriented CTA label for the primary recovery link.
string
Short promoter-style recovery copy.
string
Ready-to-send promoter-style billing response. Generation tools prefer recovery_tool instead; billing tools use this for final sales copy with checkout URLs formatted as action-specific Markdown links, e.g. Go to Checkout, Higgsfield Upgrade, Higgsfield Credit Top-up, or Higgsfield Auto-refill.
number
string
Arguments for the recovery tool.
string ("upgrade" | "topup" | "auto_refill" | "trial" | "general")
Purchase path selected for this recovery response.
Direct subscription upgrade links.
Direct one-time credit-pack links.
Best single checkout/setup link for this recovery path. Out-of-credits recovery prioritizes auto-refill when eligible, then one-time top-ups.
string
Short rationale for why this recovery offer is being shown.
object
Context for media import recovery before retrying a generation.
object
Optional context explaining why the billing recovery response was attached.
Direct auto-refill setup link.
Slug: HIGGSFIELD_MCP_JOBS_WAITLong-poll 1-12 generation jobs together without opening a widget. Waits up to timeout_seconds (default 15, max 15) for every job to reach a terminal state, then returns compact indexed statuses and result URLs. Use job IDs returned by generate_image_batch, generate_video_batch, or generate_audio_batch. For larger sets, choose groups of at most 12 and wait for each group. Permanent lookup failures are returned once without blocking the other jobs; transient lookup failures are retried within the timeout. When all_terminal is false, wait poll_after_seconds before calling again. After every wait group in the user’s generation set is terminal, collect their indexed jobs and display them with one show_generation_by_ids call when within that tool’s limit. Never use show_generations or call job_display once per batch job.

Input Parameters

array
required
Full-profile generation jobs to wait for together.
integer
Long-poll budget. Use 0 for an immediate snapshot.

Output

array
required
boolean
object
required
boolean
boolean
required
True when every job is terminal or permanently unresolvable, so no further polling is needed.
number
Slug: HIGGSFIELD_MCP_LIST_VOICESList available voices for speech and voice tools. Returns built-in preset voices plus the user’s own custom voices. Each voice has a voice_id and a voice_type (‘preset’ or ‘element’); pass that exact pair to the audio models (via generate_audio — seed_audio or text2speech_v2) and to the voice_change tool to select the speaking voice. Use the preview_url to hear a sample. Paginate with the returned next_cursor.

Input Parameters

integer
Max voices to return, default 20.
string
Pagination cursor (next_cursor from a previous list_voices result).

Output

string
Error message if voices could not be fetched.
array
Available voices.
boolean
Whether more voices are available.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Pass back as cursor to fetch the next page.
Slug: HIGGSFIELD_MCP_LIST_WEBSITE_CATEGORIESList the content categories a website can be filed under — each with a slug, label, description, and display position. create_website REQUIRES a category; call this first to get the valid slugs, then pass the closest one (‘other’ when nothing fits).

Output

string
array
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
Slug: HIGGSFIELD_MCP_LIST_WEBSITESList the websites you own — each with its id, name, slug, and live URL. Use this to find the id of a website you created earlier so you can edit, deploy, or check its status.

Output

string
array
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
Slug: HIGGSFIELD_MCP_LIST_WORKSPACESList every workspace the user can access (their private workspace plus any shared/team workspaces). The is_selected field marks which workspace MCP operations currently target. Use when the user asks which workspaces they have, or wants to switch workspace.

Output

string
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
array
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
Slug: HIGGSFIELD_MCP_MARKETING_STUDIO_V2_AVATARSWidget-internal: list the user’s Marketing Studio avatars (preset and custom) for the avatar picker.

Input Parameters

integer
integer
integer

Output

string
array
boolean
string
string
string
Slug: HIGGSFIELD_MCP_MARKETING_STUDIO_V2_COSTSWidget-internal: the Marketing Studio v2 pricing document. credits = cost_units / cost_units_per_credit; video flows cost fixed_cost_units + cost_units_per_second × duration.

Output

string
array
array
string
string
number
Slug: HIGGSFIELD_MCP_MARKETING_STUDIO_V2_CREATEWidget-internal: recreate a Marketing Studio v2 preset — validates inputs against the preset’s recreate contract and submits one generation.

Input Parameters

object
Marketing Studio avatar (UGC presets only).
string
integer
Seconds; UGC presets only.
string
saas_motion only.
string
required
string
preset.metadata.group_name, passed through from the feed.
string
string
Catalog format slug the preset belongs to (from preset.format_slugs).
string
string ("ugc" | "product_shots_people" | "product_shots" | "2d_motion" | "hypermotion" | "mixed_media" | "saas_motion" | "poster" | "ads" | "marketplace")
required
string
string
Category the preset was picked from (‘all’ allowed).
string
media_input id used as character_photo (product_shots_people).
string
preset.metadata.required_inputs, passed through from the feed.
string
Confirmed media_input id of the product image.

Output

string
string
array
string
string
string
Slug: HIGGSFIELD_MCP_MARKETING_STUDIO_V2_PRESETSWidget-internal: load a page of the Marketing Studio v2 preset feed for a category.

Input Parameters

integer
integer
Cursor from the previous page; omit for the first page.
string
required
Category slug; ‘all’ is valid.

Output

string
object
string
Slug: HIGGSFIELD_MCP_MARKETING_STUDIO_V2_STATUSWidget-internal: poll status and results of submitted Marketing Studio v2 jobs.

Input Parameters

array
required

Output

array
string
string
Slug: HIGGSFIELD_MCP_MEDIA_CONFIRMConfirm file uploads after using media_upload’s upload_url method. Call this only after every curl PUT returned HTTP 200. Supports confirming multiple uploads at once via media_ids.

Input Parameters

string ("image" | "video" | "audio" | "file")
required
Media type being confirmed. Use ‘file’ for general files (documents, archives, code) uploaded with type file.
string
Single media ID to confirm
array
1–20 media IDs to confirm in parallel

Output

string
array
Confirmed uploads. Pass media_id as the value in the medias array of generation tools.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
Slug: HIGGSFIELD_MCP_MEDIA_IMPORT_URLImport an HTTPS image, video, or audio URL into Higgsfield storage and return a confirmed media_id. Use this before generate_image/generate_video when the user provides a web media URL; generation medias should receive the returned media_id, not the original URL. Max URL payload: 50 MB.

Input Parameters

string
required
HTTPS URL of the media file to import.
string ("auto" | "image" | "video" | "audio")
Expected media type. Use auto or omit when unknown.

Output

string ("image" | "video" | "audio")
Imported media type inferred from content-type.
string
string
Non-fatal warning, e.g. imported type differed from expected type.
string
Confirmed media ID. Pass this as medias[].value in generation tools.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Original imported URL.
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Content-Type returned by the remote URL.
Slug: HIGGSFIELD_MCP_MEDIA_UPLOADUpload media for use in generation, or general files (documents, archives, code) for sharing. Returns presigned URLs for clients that can upload bytes themselves; run the generated curl commands or PUT the bytes to each upload_url, then call media_confirm. The media type is inferred from the filename extension: image/video/audio extensions become generation inputs; other whitelisted extensions (pdf, zip, tar, docx, csv, code files, …) are uploaded as general files and return a permanent URL, but cannot be used as generation inputs. General files are the agent’s own upload path — the widget does not accept them, so upload the bytes to upload_url yourself (e.g. from a code execution environment). Supports batch uploads via files[]. Do not use this for user-provided local image/video/audio in Claude Apps UI-capable clients; call media_upload_widget instead so the user chooses the file in the Higgsfield widget and the browser uploads it directly.

Input Parameters

array
1–20 files for parallel presigned URL generation
string
Only supported method. Omit this or set it to ‘upload_url’.
string
Single filename for upload
string
MIME type for single file upload, e.g. ‘image/jpeg’, ‘image/png’, or ‘video/mp4’. Inferred from filename when omitted.

Output

string
array
Presigned upload URLs. Run the curl command, then call media_confirm.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
Slug: HIGGSFIELD_MCP_MEDIA_UPLOAD_WIDGETRequired local-media intake for Higgsfield in Apps UI-capable clients. Call this immediately as the only tool in the turn when the user refers to an attached/local photo, image, video, or audio but the prompt has no confirmed media_id yet. Do not inspect /mnt/user-data/uploads, run shell/sandbox commands, or ask the user to attach the file in Claude chat; remote MCP tools cannot read chat attachments. This widget is the upload surface: the user re-selects one or more files in the browser, the browser uploads them directly to Higgsfield storage, the widget confirms them, then sends the confirmed media_id/media_ids back to Claude for the next generation or analysis tool call. Use type auto with multiple enabled when one request needs mixed media, such as reference images plus a driving video; one video and one audio file may be combined with multiple images. The widget accepts media only; for general files (archives, documents, code) use media_upload instead and upload the bytes to the presigned upload_url yourself.

Input Parameters

string ("auto" | "image" | "video" | "audio")
Expected media type. Use auto when the user has not specified image, video, or audio.
string
Optional short label shown in the widget header.
boolean
Allow selecting multiple files. Defaults to true for image/auto and false for video/audio. With type auto, one video and one audio file can be combined with multiple images.
integer
Maximum files accepted by the widget.
integer
Minimum confirmed uploads before Continue is enabled.

Output

string
required
Discriminator for the widget’s initial view.
string ("auto" | "image" | "video" | "audio")
required
Expected media type for the file picker.
string
Optional short label shown in the widget header.
object
required
boolean
Whether the widget allows multiple files.
number
Maximum files accepted by the widget.
number
Minimum confirmed uploads before Continue is enabled.
string
required
URI of the UI resource this tool binds to.
Slug: HIGGSFIELD_MCP_MODELS_EXPLOREFind generation models. Use recommend with goal + input context; use get for model constraints. Items carry supports_unlim when the model accepts free-trial unlimited generations; the top-level unlim block says whether the caller can spend them right now, and the trailing ‘Unlim configs’ text lists the configurations their allowance actually covers.

Input Parameters

string ("image" | "video" | "audio" | "3d")
Filter by output type (omit to include all)
string
Pagination cursor (next_page_token from a previous list/search result; not used by recommend)
string ("text" | "image")
Input filter: image = accepts reference media; text = text-only.
integer
Max results, default 20 for list/search, 5 for recommend
string
Model/use-case query; include input context like text-only, reference image, image-to-video, or product URL.
boolean
When true, return only models that accept free-trial unlimited generations (supports_unlim). Use it to answer “which models can I use my unlimited generations on” in one call — each returned item still carries its aspect_ratios, parameters, and durations. Omit to include all models; false is the same as omitting it.
string ("list" | "search" | "get" | "recommend")
required
The action to perform
string
Model ID (required for get)

Output

string
string
array
string
array
object
Whether the caller can spend free-trial unlimited generations right now. Combine with a model’s supports_unlim before passing use_unlim:true to generate_image / generate_video / generate_audio.
array
string
string
boolean
array
array
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string ("per_image" | "per_second")
string
string ("image" | "video" | "audio" | "3d")
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Direct URL for the primary checkout/setup action. Agents MUST show this exact link in text-only clients.
array
string
string ("show_plans_and_credits" | "media_import_url")
Canonical recovery tool for host/client routing.
Standalone tools (not catalog models) relevant to the recommend query — e.g. motion_control for recast/puppeteer, upscale_image/upscale_video for enhance, outpaint_image for expand/uncrop, reframe for a video aspect-ratio change, remove_background for cutout. Call the named tool directly; it will not appear in items.
string
CTA label for checkout_url.
object
All direct purchase/setup links returned for billing recovery.
string
Personalized seller-style headline for the recovery offer.
boolean
string
string
Short reason for opening the recovery tool.
number
string
Action-oriented CTA label for the primary recovery link.
string
Short promoter-style recovery copy.
string
Ready-to-send promoter-style billing response. Generation tools prefer recovery_tool instead; billing tools use this for final sales copy with checkout URLs formatted as action-specific Markdown links, e.g. Go to Checkout, Higgsfield Upgrade, Higgsfield Credit Top-up, or Higgsfield Auto-refill.
string
Arguments for the recovery tool.
boolean
string ("upgrade" | "topup" | "auto_refill" | "trial" | "general")
Purchase path selected for this recovery response.
Direct subscription upgrade links.
Direct one-time credit-pack links.
Best single checkout/setup link for this recovery path. Out-of-credits recovery prioritizes auto-refill when eligible, then one-time top-ups.
string
Short rationale for why this recovery offer is being shown.
object
Context for media import recovery before retrying a generation.
object
Optional context explaining why the billing recovery response was attached.
Direct auto-refill setup link.
Slug: HIGGSFIELD_MCP_MOTION_CONTROLAnimate an existing character image with the motion and camera movement from a reference video using Kling 3.0 Motion Control. Use this when the user asks to recast, puppeteer, transfer motion, or make a character follow a driving clip. Pass image_id for the character still and motion_video_id for the reference motion video; each can be a confirmed uploaded media_id or a completed generation job_id. This tool does not use prompt or count; the scene prompt and background setup are handled automatically. resolution controls output quality, and scene_control chooses whether the background is based on the image or the video.

Input Parameters

object
required
Kling 3.0 motion control parameters.

Output

object
Populated only when the tool was called with get_cost: true. No job was submitted.
string
object
array
string
object
Suggested follow-up tool call (e.g. show_marketing_studio fetch) attached to some marketing error results.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
object
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Direct URL for the primary checkout/setup action. Agents MUST show this exact link in text-only clients.
object
NO JOB WAS SUBMITTED. The caller has free unlimited generations that cover this model, and nobody has said whether to spend them. Ask the user, then call the same tool again with use_unlim: true (free) or use_unlim: false (credits). Do not pick for them.
string ("show_plans_and_credits" | "media_import_url")
Canonical recovery tool for host/client routing.
string
CTA label for checkout_url.
All direct purchase/setup links returned for billing recovery.
string
Personalized seller-style headline for the recovery offer.
string
Short reason for opening the recovery tool.
string
Live brand kit status when a generation was rejected because the kit is not ready yet.
string
Action-oriented CTA label for the primary recovery link.
string
Short promoter-style recovery copy.
string
Ready-to-send promoter-style billing response. Generation tools prefer recovery_tool instead; billing tools use this for final sales copy with checkout URLs formatted as action-specific Markdown links, e.g. Go to Checkout, Higgsfield Upgrade, Higgsfield Credit Top-up, or Higgsfield Auto-refill.
object
Set when the server auto-picked an avatar because product_ids were passed without avatars/avatar_ids (Marketing Studio video).
string
Arguments for the recovery tool.
string ("upgrade" | "topup" | "auto_refill" | "trial" | "general")
Purchase path selected for this recovery response.
Direct subscription upgrade links.
Direct one-time credit-pack links.
Best single checkout/setup link for this recovery path. Out-of-credits recovery prioritizes auto-refill when eligible, then one-time top-ups.
string
Short rationale for why this recovery offer is being shown.
object
Context for media import recovery before retrying a generation.
object
Optional context explaining why the billing recovery response was attached.
Direct auto-refill setup link.
Slug: HIGGSFIELD_MCP_OUTPAINT_IMAGEExpand or uncrop an existing image by outpainting beyond the original frame while preserving the source content. Use this when the user asks to extend the background, make an image wider or taller, change the canvas shape, or fill new edges around an image. Pass image_id for the source image and aspect_ratio for the target canvas. Optional width and height can be provided together; otherwise they default from aspect_ratio. This tool does not use prompt or count. Set params.get_cost=true to estimate credits without submitting a job.

Input Parameters

object
required
Image outpaint parameters. prompt and count are not supported.

Output

object
Populated only when the tool was called with get_cost: true. No job was submitted.
string
object
array
string
object
Suggested follow-up tool call (e.g. show_marketing_studio fetch) attached to some marketing error results.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
object
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Direct URL for the primary checkout/setup action. Agents MUST show this exact link in text-only clients.
object
NO JOB WAS SUBMITTED. The caller has free unlimited generations that cover this model, and nobody has said whether to spend them. Ask the user, then call the same tool again with use_unlim: true (free) or use_unlim: false (credits). Do not pick for them.
string ("show_plans_and_credits" | "media_import_url")
Canonical recovery tool for host/client routing.
string
CTA label for checkout_url.
All direct purchase/setup links returned for billing recovery.
string
Personalized seller-style headline for the recovery offer.
string
Short reason for opening the recovery tool.
string
Live brand kit status when a generation was rejected because the kit is not ready yet.
string
Action-oriented CTA label for the primary recovery link.
string
Short promoter-style recovery copy.
string
Ready-to-send promoter-style billing response. Generation tools prefer recovery_tool instead; billing tools use this for final sales copy with checkout URLs formatted as action-specific Markdown links, e.g. Go to Checkout, Higgsfield Upgrade, Higgsfield Credit Top-up, or Higgsfield Auto-refill.
object
Set when the server auto-picked an avatar because product_ids were passed without avatars/avatar_ids (Marketing Studio video).
string
Arguments for the recovery tool.
string ("upgrade" | "topup" | "auto_refill" | "trial" | "general")
Purchase path selected for this recovery response.
Direct subscription upgrade links.
Direct one-time credit-pack links.
Best single checkout/setup link for this recovery path. Out-of-credits recovery prioritizes auto-refill when eligible, then one-time top-ups.
string
Short rationale for why this recovery offer is being shown.
object
Context for media import recovery before retrying a generation.
object
Optional context explaining why the billing recovery response was attached.
Direct auto-refill setup link.
Slug: HIGGSFIELD_MCP_PARTICIPATE_IN_CONTESTEnter the website in the current Higgsfield app contest, together with the social-media links promoting it. A website not yet PUBLISHED to the community feed is published automatically by the entry — no need to call publish_website first. The website DOES need a live production deploy (deploy_website), else the entry is rejected. BEFORE entering, make sure the page metadata in app/src/app-meta.json is filled with real values (og_title etc.) — the auto-publish lists the website on the feed and an empty og_title makes it INVISIBLE there. Pass one or more urls, each a social-media link (YouTube, X/Twitter, Instagram, or TikTok); any other host is rejected. There is a single active contest, so no contest id is needed. Calling again for the same website OVERWRITES its urls (use it to fix or add links), it does not create a second entry.

Input Parameters

array
required
Social-media links promoting the website (YouTube / X-Twitter / Instagram / TikTok). At least one, at most ten.
string
required
The website’s id (returned by create_website).

Output

array
The submitted links.
string
string
The contest the website was entered in.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
The contest entry id.
Slug: HIGGSFIELD_MCP_PERSONAL_CLIPPER_CREATETurn YouTube videos into ready-to-share clips. This is a long-running job and can take up to 30+ minutes. Before starting, ask the user how many clips they want, which clip aspect ratio to use, and which subtitle font they prefer.

Input Parameters

array
required
YouTube video URLs.
integer
How many clips to create.
string ("9:16" | "1:1" | "16:9")
Clip aspect ratio.
string ("Noto Sans" | "Noto Serif" | "Noto Sans Display" | "IBM Plex Sans" | "M PLUS Rounded 1c" | "Bebas Neue" | "Archivo Black" | "Unbounded" | "Inter" | "Montserrat" | "Bangers" | "Permanent Marker" | "Playfair Display" | "Caveat")
Subtitle font.

Output

array
required
string
Slug: HIGGSFIELD_MCP_PERSONAL_CLIPPER_JOBSShow recent clipping jobs.

Input Parameters

integer
string

Output

array
required
string
string
Slug: HIGGSFIELD_MCP_PERSONAL_CLIPPER_STATUSCheck clip creation progress.

Input Parameters

string
required
FNF Clipify job ID from the create or jobs response.

Output

object
required
Slug: HIGGSFIELD_MCP_PRESETS_SHOWShow available Higgsfield presets for image-to-video generation. Returns preset ids, names, previews, and descriptions.

Output

string
array
required
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
URL where the user can upgrade or buy credits when generation is blocked by billing.
Slug: HIGGSFIELD_MCP_PUBLISH_WEBSITEPublish the website: lists the website’s CURRENT LIVE production deploy on the Higgsfield community feed (‘show in feed’), where other users can discover it. This does NOT deploy — deploy_website (which every build flow already runs) must have shipped the latest changes first; publishing with undeployed changes lists the OLD live build, and re-publishing does not re-deploy. BEFORE publishing, the page metadata in app/src/app-meta.json MUST be filled with real values — og_title, og_description, favicon_url, og_image_url — the feed card renders from them (read fresh from the pushed repo at publish time) and a website with an empty og_title is INVISIBLE on the feed; the live page’s own head tags are baked at build time, so deploy AFTER changing them. Also OFFER the user a cover video for the card (og_video_url) — ask their permission first (video generation costs credits), never generate it unprompted. Commit and git push the metadata (and all other changes), then deploy, BEFORE calling this. Publish when the user asks to publish / share / go live on the feed, OR when they opted in to publishing at the start of the build — in that case publish automatically once the site is deployed with its metadata filled, without waiting to be asked again. For a plain deploy without a feed listing use deploy_website instead. EXCEPTION: a website whose production was never deployed (or was taken down by unpublish) falls back to deploying first — that returns status ‘pending’ while CI runs and the website is listed automatically once the deploy succeeds (check with website_status).

Input Parameters

string
required
The website’s id (returned by create_website).

Output

string
The live production URL when the deploy succeeded.
string
The published site’s title (from its og:title / <title>).
string
Build log when the deploy failed.
string
deployed / failed / pending (CI still running).
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Echo of the input id — the widget’s publish/contest buttons need it.
string
The published site’s favicon URL.
string
The published site’s OG banner image URL.
string
The website’s community-feed listing page on Higgsfield — show it to the user.
boolean
Whether the website is now on the community feed.
Slug: HIGGSFIELD_MCP_REFRAMEExpand or reframe an existing video to a new aspect ratio while preserving the source content. Use this when the user asks to make a video vertical, horizontal, square, wider, taller, or fill new edges around a video. Pass medias with exactly one source video and aspect_ratio for the target canvas. Optional image references can guide the filled area; optional start_image can pin the first frame when the user provides a first-frame anchor. For source videos over 15 seconds, pass duration_seconds and resolution and use only the source video. This tool does not use prompt or count. Set params.get_cost=true to estimate credits without submitting a job.

Input Parameters

object
required
Video reframe parameters. prompt and count are not supported.

Output

object
Populated only when the tool was called with get_cost: true. No job was submitted.
string
object
array
string
object
Suggested follow-up tool call (e.g. show_marketing_studio fetch) attached to some marketing error results.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
object
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Direct URL for the primary checkout/setup action. Agents MUST show this exact link in text-only clients.
object
NO JOB WAS SUBMITTED. The caller has free unlimited generations that cover this model, and nobody has said whether to spend them. Ask the user, then call the same tool again with use_unlim: true (free) or use_unlim: false (credits). Do not pick for them.
string ("show_plans_and_credits" | "media_import_url")
Canonical recovery tool for host/client routing.
string
CTA label for checkout_url.
All direct purchase/setup links returned for billing recovery.
string
Personalized seller-style headline for the recovery offer.
string
Short reason for opening the recovery tool.
string
Live brand kit status when a generation was rejected because the kit is not ready yet.
string
Action-oriented CTA label for the primary recovery link.
string
Short promoter-style recovery copy.
string
Ready-to-send promoter-style billing response. Generation tools prefer recovery_tool instead; billing tools use this for final sales copy with checkout URLs formatted as action-specific Markdown links, e.g. Go to Checkout, Higgsfield Upgrade, Higgsfield Credit Top-up, or Higgsfield Auto-refill.
object
Set when the server auto-picked an avatar because product_ids were passed without avatars/avatar_ids (Marketing Studio video).
string
Arguments for the recovery tool.
string ("upgrade" | "topup" | "auto_refill" | "trial" | "general")
Purchase path selected for this recovery response.
Direct subscription upgrade links.
Direct one-time credit-pack links.
Best single checkout/setup link for this recovery path. Out-of-credits recovery prioritizes auto-refill when eligible, then one-time top-ups.
string
Short rationale for why this recovery offer is being shown.
object
Context for media import recovery before retrying a generation.
object
Optional context explaining why the billing recovery response was attached.
Direct auto-refill setup link.
Slug: HIGGSFIELD_MCP_REMOVE_BACKGROUNDRemove or cut out the background from an existing image or video. Use this when the user asks for background removal, a transparent background, an isolated subject, a clean cutout, or a subject-only asset. Pass media_id for the source media and media_type as image or video; the matching background remover is selected automatically. This tool does not use prompt, count, or style parameters.

Input Parameters

object
required
Background removal parameters.

Output

object
Populated only when the tool was called with get_cost: true. No job was submitted.
string
object
array
string
object
Suggested follow-up tool call (e.g. show_marketing_studio fetch) attached to some marketing error results.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
object
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Direct URL for the primary checkout/setup action. Agents MUST show this exact link in text-only clients.
object
NO JOB WAS SUBMITTED. The caller has free unlimited generations that cover this model, and nobody has said whether to spend them. Ask the user, then call the same tool again with use_unlim: true (free) or use_unlim: false (credits). Do not pick for them.
string ("show_plans_and_credits" | "media_import_url")
Canonical recovery tool for host/client routing.
string
CTA label for checkout_url.
All direct purchase/setup links returned for billing recovery.
string
Personalized seller-style headline for the recovery offer.
string
Short reason for opening the recovery tool.
string
Live brand kit status when a generation was rejected because the kit is not ready yet.
string
Action-oriented CTA label for the primary recovery link.
string
Short promoter-style recovery copy.
string
Ready-to-send promoter-style billing response. Generation tools prefer recovery_tool instead; billing tools use this for final sales copy with checkout URLs formatted as action-specific Markdown links, e.g. Go to Checkout, Higgsfield Upgrade, Higgsfield Credit Top-up, or Higgsfield Auto-refill.
object
Set when the server auto-picked an avatar because product_ids were passed without avatars/avatar_ids (Marketing Studio video).
string
Arguments for the recovery tool.
string ("upgrade" | "topup" | "auto_refill" | "trial" | "general")
Purchase path selected for this recovery response.
Direct subscription upgrade links.
Direct one-time credit-pack links.
Best single checkout/setup link for this recovery path. Out-of-credits recovery prioritizes auto-refill when eligible, then one-time top-ups.
string
Short rationale for why this recovery offer is being shown.
object
Context for media import recovery before retrying a generation.
object
Optional context explaining why the billing recovery response was attached.
Direct auto-refill setup link.
Slug: HIGGSFIELD_MCP_RENAME_WEBSITERename the website’s SUBDOMAIN (the slug in its public URL). The site is re-deployed under the new subdomain and the OLD subdomain STOPS WORKING — anyone holding the old URL must be given the new one. Storage (database, files, config) and the code repo are KEPT; only the public address changes. Runs a full re-deploy and can take a couple of minutes; returns once the site is live at the new URL. Fails if the new subdomain is already taken or reserved, or if a deploy is already in flight — pick another subdomain and retry.

Input Parameters

string
required
The new subdomain (the slug in the public URL). Lowercase letters, digits and hyphens; must be globally unique and not a reserved name.
string
required
The website’s id (returned by create_website).

Output

string
Live URL under the new subdomain.
string
The website’s subdomain after the rename.
string
The subdomain it had before (that URL no longer works).
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
Slug: HIGGSFIELD_MCP_RESOLVE_EXPLAINER_PRESETResolve a explainer video style preset (from get_explainer_presets) into a style reference media_id: the backend imports the preset’s style image into the user’s media storage. Pass the returned media_id as the style reference image in generation calls for every scene of the explainer.

Input Parameters

string
required
Preset id from get_explainer_presets.

Output

string
required
string
required
Imported style image — use as the style reference in generations.
string
required
Slug: HIGGSFIELD_MCP_REVEAL_GENERATIONConfirm the user has rights to the content of an ip_detected generation and flip its status to completed. Backend accepts only seedance-family jobs (cs_3_0, seedance_2_0, ms_video, etc) and only while the job is still in ip_detected state. Returns the updated generation. Used by the job-list widget’s Reveal button after the user accepts the rights confirmation modal.

Input Parameters

string
required
Job ID of the ip_detected generation to reveal.

Output

string
boolean
object
Updated generation (status flipped to completed).
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
Slug: HIGGSFIELD_MCP_SANDBOX_EXECExecute a shell command in a remote Higgsfield cloud Linux sandbox — NOT your local machine or the client’s own shell. Whenever a task needs shell tooling (ffmpeg, image/file conversion, scripting), use this tool, never a built-in or local bash/shell tool: only this sandbox has the media toolchain preinstalled and can reach the user’s Higgsfield media. Preinstalled: ffmpeg/ffprobe, ImageMagick, sox, python3 with Pillow and faster-whisper, node/npm/npx, sharp-cli, Playwright with headless Chromium, caption fonts (Metropolis, Montserrat), zip/unzip, git, curl, jq. Use it for media processing (trim, convert, overlay, concat with ffmpeg), image manipulation, file conversion, scripting, and packaging that dedicated tools don’t cover. The sandbox is isolated per user and is discarded ~10 seconds after a call finishes, so files in /home/user only survive between back-to-back calls — chain multi-step work into a single command (&&) and export results before finishing, or expect to re-download inputs. It has internet access: bring files in with curl from media URLs (media_import_url or generation results). For an output created here, call media_upload BEFORE starting the producing command, then append curl -f -X PUT --upload-file <file> '<upload_url>' to that SAME command so the ephemeral file is uploaded before it exits; call media_confirm only after HTTP 200. Never pass a sandbox path to media_upload_and_confirm: that tool accepts only client attachments. Commands run in /home/user and time out after timeout_seconds (default 60, max 120); for longer work (large renders, installs) set background:true and poll the returned log/status files with later sandbox_exec calls. Background work receives a 15-minute sandbox lease, and shorter poll calls never reduce its remaining lifetime. Set restart:true to discard the sandbox and start clean. Workflow bundle scripts are already installed in every sandbox under $HF_WORKFLOWS (/home/user/.higgsfield/workflows), laid out as $HF_WORKFLOWS/<workflow>/scripts/… — run them straight from there (they survive restart:true), and never paste script contents into the command.

Input Parameters

string
required
Shell command to run (bash). Runs in the persistent per-user sandbox.
boolean
Discard the current sandbox (all files and processes) and start a fresh one before running the command.
boolean
Run the command detached and return immediately with a pid, log_path, and status_path. Poll with a later sandbox_exec call; stop with kill <pid>.
integer
Seconds before the command is killed (default 60, max 120). Ignored with background:true.

Output

number
Background process id (background:true only).
string
string
string
string
File collecting the background command’s combined output (background:true only).
number
boolean
True when stdout/stderr were truncated. Re-run with a narrower command (head, grep, wc) for full data.
string
string
File containing the terminal exit code once a background command finishes.
Slug: HIGGSFIELD_MCP_SCENE_BUILDER_3D_CREATE_PROJECTCreate a new private 3D Jutsu project for the authenticated user. Supply a descriptive name; the service assigns ownership and the project ID. Use this when the user requests a new project or a new standalone scene. For an existing scene, use scene_builder_3d_list_projects instead. Pass the returned projectId explicitly to subsequent tools; creation does not set a global active project. Call scene_builder_3d_get_project, then scene_builder_3d_query_python to inspect the initial scene and obtain guards before scene_builder_3d_run_python or scene_builder_3d_import_asset. Creation alone does not produce a committed GLB: scene_builder_3d_show_scene becomes available after the first successful edit or import. This call is not idempotent. If the response is interrupted or uncertain, use scene_builder_3d_list_projects to find the new project before retrying; repeating creation can create a duplicate.Finish each completed scene creation, edit, or import task by calling scene_builder_3d_show_scene once as the final 3D Jutsu tool call before your final reply, after mutations have settled and verification is complete. Pass the same projectId and the exact committed revision of the final result: revisionAfter from the final successful mutation, or the settled project.revision after an import. Do not guess the revision. This shows the result to the user; a text summary or download link alone does not finish scene delivery.

Input Parameters

string
required
Name for the new private 3D Jutsu project.

Output

boolean
required
object
required
string
required
string
required
string
required
Open this project in 3D Jutsu.
object
required
Slug: HIGGSFIELD_MCP_SCENE_BUILDER_3D_GET_ARTIFACTResolve a short-lived download for an image or video that a successful Python operation published through artifacts. Use the artifact ID and operation ID or revision returned by that operation; do not invent IDs or filesystem paths. Query artifacts can be operation-scoped without a new committed revision. This retrieves an existing artifact and does not render one. To create a preview, render and publish it with scene_builder_3d_query_python or scene_builder_3d_run_python. Inspect the returned image using the client’s image capability before judging framing, lighting, materials, and geometry. If the client cannot inspect it, describe that limitation rather than claiming a visual check passed.Finish each completed scene creation, edit, or import task by calling scene_builder_3d_show_scene once as the final 3D Jutsu tool call before your final reply, after mutations have settled and verification is complete. Pass the same projectId and the exact committed revision of the final result: revisionAfter from the final successful mutation, or the settled project.revision after an import. Do not guess the revision. This shows the result to the user; a text summary or download link alone does not finish scene delivery.

Input Parameters

integer
Exact committed revision inspected; do not guess.
string
required
Project ID from scene_builder_3d_list_projects, scene_builder_3d_create_project, or the user’s explicit selection. Required on every project-scoped tool.
string
required
string
Stable ID for this logical operation. Reuse only for an identical request, including code and guards.

Output

boolean
required
object
required
object
required
string
required
Open this project in 3D Jutsu.
Slug: HIGGSFIELD_MCP_SCENE_BUILDER_3D_GET_BLENDResolve a short-lived download for the current committed editable Blender file, or a specified historical revision. This retrieves the existing scene; it does not create a revision or render a preview. Settle any active mutation with scene_builder_3d_get_operation first when you need its result. Use scene_builder_3d_get_glb for portable model delivery and scene_builder_3d_get_artifact for published images or videos.

Input Parameters

integer
Exact committed revision inspected; do not guess.
string
required
Project ID from scene_builder_3d_list_projects, scene_builder_3d_create_project, or the user’s explicit selection. Required on every project-scoped tool.

Output

boolean
required
object
required
object
required
string
required
Open this project in 3D Jutsu.
Slug: HIGGSFIELD_MCP_SCENE_BUILDER_3D_GET_GLBFor an interactive scene preview use scene_builder_3d_show_scene. Resolve a short-lived download for the current committed GLB, or a specified historical revision. This retrieves an existing export; it does not run Blender, render, or create a new export. Settle any active mutation with scene_builder_3d_get_operation first if you need its result. Use GLB for portable scene delivery, and scene_builder_3d_get_blend for the editable Blender source. Procedural shading, world lighting, and some Blender features may differ in GLB. A successful download does not establish that the exported scene looks correct.

Input Parameters

integer
Exact committed revision inspected; do not guess.
string
required
Project ID from scene_builder_3d_list_projects, scene_builder_3d_create_project, or the user’s explicit selection. Required on every project-scoped tool.

Output

boolean
required
object
required
object
required
string
required
Open this project in 3D Jutsu.
Slug: HIGGSFIELD_MCP_SCENE_BUILDER_3D_GET_OPERATIONRead or wait for a submitted Python operation in this project. Only succeeded, failed, timed_out, and expired are terminal; all other statuses require another poll using the same project and operation IDs. An HTTP success or a wait timeout does not mean the operation finished. Do not submit another mutation while one is active. On success, use the returned revision and scene sequence for subsequent work; obtain published images and videos through scene_builder_3d_get_artifact. On failure, inspect the error and re-read project state before deciding to retry. Do not blindly resubmit a failed operation under another ID.Finish each completed scene creation, edit, or import task by calling scene_builder_3d_show_scene once as the final 3D Jutsu tool call before your final reply, after mutations have settled and verification is complete. Pass the same projectId and the exact committed revision of the final result: revisionAfter from the final successful mutation, or the settled project.revision after an import. Do not guess the revision. This shows the result to the user; a text summary or download link alone does not finish scene delivery.

Input Parameters

string
required
Project ID from scene_builder_3d_list_projects, scene_builder_3d_create_project, or the user’s explicit selection. Required on every project-scoped tool.
string
required
Stable ID for this logical operation. Reuse only for an identical request, including code and guards.
integer

Output

boolean
required
object
string
boolean
required
False while the operation still needs polling; true includes success and failure.
object
required
string
required
Open this project in 3D Jutsu.
object
Slug: HIGGSFIELD_MCP_SCENE_BUILDER_3D_GET_PROJECTRead a 3D Jutsu project’s current revision, scene sequence, active operation, and committed artifacts. Obtain projectId from scene_builder_3d_list_projects, scene_builder_3d_create_project, or an explicit user selection. An authorized project with exists: false is a valid empty scene at revision 0. Use scene_builder_3d_query_python to inspect actual objects, dimensions, materials, cameras, and lights before editing. If an operation is active, use scene_builder_3d_get_operation to settle it before another mutation. Scene edits use scene_builder_3d_run_python with the exact revision and scene sequence inspected; never guess these guards.Finish each completed scene creation, edit, or import task by calling scene_builder_3d_show_scene once as the final 3D Jutsu tool call before your final reply, after mutations have settled and verification is complete. Pass the same projectId and the exact committed revision of the final result: revisionAfter from the final successful mutation, or the settled project.revision after an import. Do not guess the revision. This shows the result to the user; a text summary or download link alone does not finish scene delivery.

Input Parameters

string
required
Project ID from scene_builder_3d_list_projects, scene_builder_3d_create_project, or the user’s explicit selection. Required on every project-scoped tool.

Output

boolean
required
boolean
required
object
required
string
required
Open this project in 3D Jutsu.
Slug: HIGGSFIELD_MCP_SCENE_BUILDER_3D_IMPORT_ASSETImport a confirmed catalog GLB from scene_builder_3d_search_assets into the selected project as a collaborative scene entity. Supply the catalog’s asset ID, not a URL. The tool runtime resolves and uploads the bytes, reads the project guards, submits the import, and waits for it to appear in the settled scene. Do not import while another mutation is active. After import, inspect dimensions, placement, orientation, contact, and materials with scene_builder_3d_query_python before further edits. Do not repeat the whole import to poll: it can create a duplicate. If an import fails, report the error; never fall back to Python network calls or base64-encoded model bytes. Copy catalogSearch from the search result’s importArguments. If settled is false, poll scene_builder_3d_get_project until appliedSceneSequence reaches targetSceneSequence. If submissionUnknown is true, inspect the returned entityId before deciding to retry. This version accepts catalog assets only.Finish each completed scene creation, edit, or import task by calling scene_builder_3d_show_scene once as the final 3D Jutsu tool call before your final reply, after mutations have settled and verification is complete. Pass the same projectId and the exact committed revision of the final result: revisionAfter from the final successful mutation, or the settled project.revision after an import. Do not guess the revision. This shows the result to the user; a text summary or download link alone does not finish scene delivery.

Input Parameters

string
string
required
Confirmed catalog ID from scene_builder_3d_search_assets. Attachment IDs are not supported by this tool.
string
required
Project ID from scene_builder_3d_list_projects, scene_builder_3d_create_project, or the user’s explicit selection. Required on every project-scoped tool.
object
Editor/glTF coordinates: metres, Y up, XYZW quaternion. Blender bpy coordinates are Z up; account for that when comparing transforms.
string
required
Stable ID for this logical operation. Reuse only for an identical request, including code and guards.
integer
Wait up to this many seconds; poll scene_builder_3d_get_operation if still active.
Copy catalogSearch from the search result’s importArguments so the catalog ID can be resolved in the same result set.

Output

boolean
required
string
required
object
string
required
string
required
boolean
Whether the accepted import has reached the committed scene.
string
required
string
integer
string
required
string
string
required
Open this project in 3D Jutsu.
string
required
integer
boolean
Inspect entityId before retrying: the import may already have been accepted.
integer
Poll until appliedSceneSequence reaches this value.
integer
Slug: HIGGSFIELD_MCP_SCENE_BUILDER_3D_LIST_PROJECTSDiscover the authenticated user’s 3D Jutsu projects before choosing a scene to read or edit. Follow nextCursor to see more results. Use the selected project’s id as projectId in every project-scoped 3D Jutsu tool; no call sets a global active project. Match the user’s named project, and ask them to choose if the result is ambiguous. Then call scene_builder_3d_get_project for its current state. A project’s presence here does not bypass permission checks on subsequent calls. To start a new project, use scene_builder_3d_create_project.

Input Parameters

integer
string

Output

boolean
required
array
required
string
required
Slug: HIGGSFIELD_MCP_SCENE_BUILDER_3D_QUERY_PYTHONInspect the latest settled Blender scene without committing changes. bpy and the artifacts registry are available; assign concise JSON-serializable findings to result. Query exact names, metre-scale dimensions, transforms, parents, collections, materials, cameras, lights, visibility, and animation settings as needed. Inspect Blender RNA when an API or enum is uncertain. Temporary scene changes are discarded, including camera changes used for inspection. A query can render and publish images for visual inspection: allocate a target with artifacts.file(name="preview.png", media_type="image/png"), write the image to target.path, and call target.publish(). Resolve published IDs with scene_builder_3d_get_artifact. Use the successful query’s revisionBefore and sceneSequenceAfter as the guards for the next scene_builder_3d_run_python call. If still active, poll scene_builder_3d_get_operation. Reuse an operation ID only to retry the identical request. Imported model bytes must enter through scene_builder_3d_import_asset; do not fetch URLs or embed file bytes in Python.

Input Parameters

string
required
Use bpy and artifacts; assign JSON-serializable findings to result. Files persist only via artifacts.file(name=…, media_type=…), writing to target.path, then target.publish(). At most eight PNG/JPEG/MP4 files, 512 MiB each and 1 GiB total; images at most 16384 pixels per side and 64 MP. Invalid published files fail the operation. Set image_settings.media_type=‘IMAGE’ before PNG/JPEG, or ‘VIDEO’ before FFMPEG with MPEG4/H264. No network fetches or embedded model bytes; use scene_builder_3d_import_asset.
string
required
Project ID from scene_builder_3d_list_projects, scene_builder_3d_create_project, or the user’s explicit selection. Required on every project-scoped tool.
string
required
Stable ID for this logical operation. Reuse only for an identical request, including code and guards.
integer
Wait up to this many seconds; poll scene_builder_3d_get_operation if still active.

Output

boolean
required
object
string
boolean
required
False while the operation still needs polling; true includes success and failure.
object
required
string
required
Open this project in 3D Jutsu.
object
Slug: HIGGSFIELD_MCP_SCENE_BUILDER_3D_RUN_PYTHONCommit one coherent Blender scene edit against the exact revision and scene sequence you inspected with scene_builder_3d_get_project or scene_builder_3d_query_python. bpy and artifacts are available; assign JSON-serializable findings to result. Keep one mutation active per project, including imports. If this operation remains active, poll scene_builder_3d_get_operation before editing again. Reuse operationId only for the identical code and preconditions. On a stale-state conflict, inspect the scene again and regenerate the edit with fresh guards and a new operation ID. A successful mutation advances revisionAfter.Build editable scenes at metre scale with descriptive object names and semantic parts. For a new multi-object scene, establish the delivery camera, a motivated key light, fill, and ambient light with the first blockout. Preserve existing scene intent when editing. Work through silhouette, measured proportions, depth, contact, camera framing, then detail; adjust lights with the geometry. Keep modifiers and material roles editable, account for parent transforms, and prefer shared mesh data over large loops of creation operators. Use portable Principled materials and existing embedded textures when GLB delivery matters; procedural shaders and world lighting do not reliably carry into GLB. Use Point, Sun, or Spot lights for portable lighting. Do not invent texture paths or fetch external files from Blender.This worker pins Blender 5.2. Use BLENDER_EEVEE, BLENDER_WORKBENCH, or CYCLES, not BLENDER_EEVEE_NEXT. Query RNA instead of assuming older APIs such as use_bloom, use_auto_smooth, or render tile settings exist. Code is capped at 256 KiB, and execution and checkpoint/export must fit the configured worker deadline. Keep renders small and samples low; split expensive work into coherent edits. Committed scenes are finalized with Eevee and Khronos PBR Neutral. For animation, establish fps, frame range, rest pose, and timing first; key only intended properties, choose interpolation deliberately, and inspect rest, peak, final pose, contacts, and loop seams. Avoid promising long video renders before validating cost.Successful execution does not establish visual correctness. Render from the delivery camera, publish the image through artifacts, then retrieve it with scene_builder_3d_get_artifact and inspect it using the client’s image capability. Fix framing, floating/intersecting parts, missing textures, and lighting before claiming completion. Workbench does not test scene lights; use a small Eevee render for that. If visual inspection is unavailable, state what remains unverified. Use scene_builder_3d_import_asset for models and scene_builder_3d_get_glb or scene_builder_3d_get_blend when the user needs the committed files.Finish each completed scene creation, edit, or import task by calling scene_builder_3d_show_scene once as the final 3D Jutsu tool call before your final reply, after mutations have settled and verification is complete. Pass the same projectId and the exact committed revision of the final result: revisionAfter from the final successful mutation, or the settled project.revision after an import. Do not guess the revision. This shows the result to the user; a text summary or download link alone does not finish scene delivery.

Input Parameters

string
required
Use bpy and artifacts; assign JSON-serializable findings to result. Files persist only via artifacts.file(name=…, media_type=…), writing to target.path, then target.publish(). At most eight PNG/JPEG/MP4 files, 512 MiB each and 1 GiB total; images at most 16384 pixels per side and 64 MP. Invalid published files fail the operation. Set image_settings.media_type=‘IMAGE’ before PNG/JPEG, or ‘VIDEO’ before FFMPEG with MPEG4/H264. No network fetches or embedded model bytes; use scene_builder_3d_import_asset.
integer
required
Exact committed revision inspected; do not guess.
string
required
Project ID from scene_builder_3d_list_projects, scene_builder_3d_create_project, or the user’s explicit selection. Required on every project-scoped tool.
string
required
Stable ID for this logical operation. Reuse only for an identical request, including code and guards.
integer
Wait up to this many seconds; poll scene_builder_3d_get_operation if still active.
integer
required
Exact settled scene sequence inspected by your query.

Output

boolean
required
object
string
boolean
required
False while the operation still needs polling; true includes success and failure.
object
required
string
required
Open this project in 3D Jutsu.
object
Slug: HIGGSFIELD_MCP_SCENE_BUILDER_3D_SEARCH_ASSETSSearch the curated GLB model catalog available to 3D Jutsu. This read is authorized against projectId; the catalog itself is shared. Pass a returned assetId to scene_builder_3d_import_asset for the same selected project. Search results are available models, not objects already present in the scene. Inspect existing scene objects with scene_builder_3d_query_python before deciding what to add. Never invent an asset ID or turn a catalog URL into Python download code. Copy the returned importArguments, including catalogSearch, into scene_builder_3d_import_asset.

Input Parameters

integer
string
required
Project ID from scene_builder_3d_list_projects, scene_builder_3d_create_project, or the user’s explicit selection. Required on every project-scoped tool.

Output

boolean
required
integer
required
array
required
string
required
Open this project in 3D Jutsu.
Slug: HIGGSFIELD_MCP_SCENE_BUILDER_3D_SHOW_SCENEShow a minimal interactive 3D Jutsu scene preview with orbit, pan, zoom, a basic animation timeline with play/pause and seeking, and a link to the website. Choose projectId with scene_builder_3d_list_projects, scene_builder_3d_create_project, or the user’s explicit selection. Pass revisionAfter from a successful edit to show that exact result, or omit revision for the latest committed GLB. Wait for edits to settle with scene_builder_3d_get_operation before showing their result. This reads an existing export; it never starts Blender, edits the scene, or includes uncommitted collaborative changes. Call this when the user asks to see the scene. For a completed scene creation, edit, or import task, call it once as the final 3D Jutsu tool call before your final reply, after settlement and verification. The widget is for the user to inspect; it does not give the agent visual evidence. Use scene_builder_3d_query_python and scene_builder_3d_get_artifact for the agent’s visual verification. If the client cannot display widgets, provide the returned projectUrl.

Input Parameters

integer
Committed revision to preview. Omit for the latest committed revision; use revisionAfter to show the exact result of an edit.
string
required
Project ID from scene_builder_3d_list_projects, scene_builder_3d_create_project, or the user’s explicit selection. Required on every project-scoped tool.

Output

boolean
required
string
required
object
required
object
required
integer
required
string
required
string
required
Open this project in 3D Jutsu.
Slug: HIGGSFIELD_MCP_SELECT_WORKSPACESet or clear the active workspace — the one all subsequent MCP operations bill against and read from (generations, balance, transactions, uploads, custom references). How to work with workspaces: (1) call list_workspaces first to see the user’s workspaces with their id, plan, available credits, and which one is currently active (is_selected); (2) call select_workspace with the chosen workspace_id to switch — e.g. to run and bill work under a shared/team workspace instead of the private default; (3) call again with clear: true to return to the default private workspace. The selection persists across sessions and clients until changed or cleared, so it stays in effect for later turns without re-selecting. When the user belongs to more than one workspace, confirm which one to use before billable operations. Returns an error if the workspace doesn’t exist or the user isn’t a member.

Input Parameters

boolean
When true, clear the selected workspace instead of selecting one.
string
Workspace UUID from list_workspaces. Required unless clear is true.

Output

string
boolean
object
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
Slug: HIGGSFIELD_MCP_SHORTS_STUDIO_CREATEStart a Shorts Studio short: restyle one uploaded source video (4s–120s) into a set of AI-generated short-form clips using a style preset. PAID — reserves credits. Prerequisites, gathered in whatever order fits the conversation: (1) a style preset — pick one via shorts_studio_list_presets or make one with shorts_studio_create_preset; (2) a source video — an uploaded video_input id from media_upload_widget (type=video). If the user hasn’t provided a source video yet, ask them to upload one before calling this. Output orientation defaults to 9:16 (vertical); pass aspect_ratio:‘16:9’ for horizontal. Returns a session with empty job_ids; poll shorts_studio_status until clips appear. Set get_cost=true with duration_seconds to estimate the credit cost without submitting a job — no preset or source video needed for the estimate.

Input Parameters

boolean
If true, return the credit cost for a short of duration_seconds without submitting a job.
string
Style preset id from shorts_studio_list_presets or shorts_studio_create_preset. Required unless get_cost is true.
string
Only 720p is supported.
string ("9:16" | "16:9")
Output orientation. Defaults to 9:16 (vertical); use 16:9 for horizontal.
string ("cms" | "user")
Preset library: ‘user’ or ‘cms’ (the item’s preset_source). Required unless get_cost is true.
string
Uploaded source video’s video_input id (from media_upload_widget, type=video). Required unless get_cost is true.
number
Source video duration in seconds. Required when get_cost is true.

Output

string
object
Populated only when called with get_cost: true. No job was submitted.
string ("queued" | "in_progress" | "completed")
array
string
string
Slug: HIGGSFIELD_MCP_SHORTS_STUDIO_CREATE_PRESETCreate a user-owned Shorts Studio style preset from reference media (videos + images). This just stores a STYLE — no generation, no credits. Reference media must be public https URLs (use an uploaded media’s url or media_import_url first). Limits: ≤10 media total, each video’s duration ≤30s (send duration so the cap applies). Returns the id and preset_source to feed into shorts_studio_create. If the user did not give a name, invent a random friendly two-word name yourself (e.g. ‘Amber Drift’, ‘Neon Tide’, ‘Velvet Dusk’) — never leave it blank or ask.

Input Parameters

string
required
Preset name. If the user didn’t provide one, generate a random friendly two-word name (e.g. ‘Amber Drift’, ‘Neon Tide’) rather than asking or leaving it empty.
string
Optional style direction (e.g. ‘cinematic teal & orange’).
string
Optional thumbnail URL.
array
Style-reference images.
array
Style-reference videos.

Output

string
required
string
required
string
required
Slug: HIGGSFIELD_MCP_SHORTS_STUDIO_LIST_PRESETSBrowse Shorts Studio style presets — the visual STYLE a short is restyled toward. Use this when the user wants to make a short and needs to choose a look: they can pick one of these or create their own style with shorts_studio_create_preset. Returns the user’s own presets first, then the CMS library; each item carries a preset_source to pass straight into shorts_studio_create. Paginated: if next_cursor is not null, pass it as cursor to get the next page.

Input Parameters

string
Pass next_cursor from a previous response to get the next page.

Output

array
required
boolean
required
string
required
boolean
required
Slug: HIGGSFIELD_MCP_SHORTS_STUDIO_LIST_SESSIONSList the caller’s past Shorts Studio sessions (newest first) to find a session_id to poll with shorts_studio_status.

Input Parameters

integer
Page size (default 20).
number
created_at cursor from a prior response.

Output

array
required
string
required
boolean
required
Slug: HIGGSFIELD_MCP_SHORTS_STUDIO_STATUSPoll one Shorts Studio session. Returns {id, status, job_ids}. status=‘completed’ means every clip job is terminal (not necessarily successful). Poll each job_id via job_status for its clip video url and per-clip status.

Input Parameters

string
required
Session id from shorts_studio_create or shorts_studio_list_sessions.

Output

string
required
string ("queued" | "in_progress" | "completed")
required
array
required
string
required
string
required
Slug: HIGGSFIELD_MCP_SHOW_CHARACTERSSoul Characters widget — reusable trained identity models. Actions: list (browse), train (needs name + 5-20 ref images, ~10 min, non-blocking — widget polls), status (inspect by soul_id). Presence of name/images/medias ⇒ train mode. Call train only on explicit ask for a reusable Soul / digital twin / identity, or when 5+ ref photos are supplied. Ref images accept: media_id UUIDs from media_confirm, completed image-job IDs, or https URLs. Never local paths — upload via media_upload → PUT bytes → media_confirm first.CONSTRAINTS:
  • Trained Soul is usable ONLY with soul_2 (Soul V2) and soul_cinematic (Soul Cinema). For any other model, the user needs show_reference_elements.
  • ONE soul_id per generation. Multi-character shots (‘me + friend’, ‘two people’) must use show_reference_elements (supports multiple <<<UUID>>> placeholders).
AMBIGUITY GUARD — character/avatar/digital-twin/‘use my face’ requests without a chosen path: do NOT call this tool yet; ask the user to pick:
  1. Train Soul (this tool) — identity-faithful, ONE person, 5-20 photos, ~10 min, Soul V2 / Cinema only.
  2. Save as Element (show_reference_elements action=create) — instant, single image, multiple subjects allowed, works with Nano Banana Pro / 2, GPT Image 2, Seedream 4.5 / 5 lite, Cinema Studio Image 2.5, Cinema Studio Video 2 / 3.0, Seedance 2.0, Kling 3.0. → Soul signals: ‘train’ / ‘digital twin’ / ‘identity’ / 5+ photos of same person. → Force Elements: >1 character in shot, non-person subject, single image, mention of a non-Soul model, instant result wanted.
After ready: generate_image with model: 'soul_2' (or soul_cinematic) + the returned soul_id.

Input Parameters

string
Character name, required for action=train.
integer
Number of characters per page.
string ("soul" | "soul_2" | "soul_cinematic")
Character type. Use soul_2 for model=‘soul_2’; use soul_cinematic for model=‘soul_cinematic’; use soul for legacy Soul references.
string
Mode selector: list, train/create, or status/get.
number
Pagination cursor from previous response’s next_cursor.
array
For Soul training: returned media_id UUIDs from media_confirm, completed image generation job IDs, or https image URLs. Required with medias to total 5-20 images for action=train. Do not pass local file paths.
array
Chat media references to resolve as training images for action=train. Values may be media_id UUIDs, completed image generation job IDs, or https image URLs.
string ("ready" | "training" | "failed")
List filter. Use ready to find characters available for generation.
string
Character id for action=status.

Output

string
string
array
boolean
True when a new training job was started.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
string
ID of the character that just started training; used by the widget for the live progress pill.
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
ID of the character returned by status/get.
Slug: HIGGSFIELD_MCP_SHOW_GENERATION_BY_IDSRender exactly 1-60 requested generation jobs in the full-profile gallery widget, ordered by index and paginated locally in groups of 12. Use once every jobs_wait group is terminal for generate_image_batch, generate_video_batch, or generate_audio_batch. Pass the complete indexed set collected from the batch tools. This tool fetches only those job IDs in bounded groups: it never loads generation history, uses cursors, requests additional pages, or adds other jobs. Do not use show_generations or job_display to present a completed batch.

Input Parameters

array
required
Exact full-profile generation jobs to display. Results are ordered by index and paginated locally.

Output

array
required
array
required
boolean
required
True when every requested job ID was fetched. Failed generations still count as found.
Slug: HIGGSFIELD_MCP_SHOW_GENERATIONSBrowse completed non-Marketing Studio generation history and render one paginated page in the gallery widget. Returns generations with {id, type, status, model, params, results}. Use only when the user explicitly asks to browse regular generation history. Do not use this history tool after generate_*_batch or jobs_wait; show an exact completed batch with one show_generation_by_ids call instead. Use show_marketing_studio_generations for Marketing Studio video/image/ad history. Pass a prior generation’s id as value in the medias array of a new generation to reuse it. Use job_display only to inspect one specific previous result. Paginated: if next_cursor is not null, pass it as cursor to get the next page.

Input Parameters

string
Number of results per page
string ("image" | "video" | "audio" | "3d")
Filter by media type
string
Pass next_cursor from previous response to get next page

Output

string
Error message if the list could not be fetched.
array
Array of generations. Absent on error.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Pass as cursor to get next page. Null if no more results.
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
Slug: HIGGSFIELD_MCP_SHOW_MARKETING_STUDIO_GENERATIONSBrowse past completed Marketing Studio generations only. Returns Marketing Studio video and ad/image generations with {id, type, status, model, params, results}. Use show_generations for non-Marketing Studio image/video history.

Input Parameters

integer
Number of results per page
number
Pass next_cursor from previous response to get the next page

Output

string
Error message if the list could not be fetched.
array
Array of Marketing Studio generations. Absent on error.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Pass as cursor to get next page. Null if no more results.
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
Slug: HIGGSFIELD_MCP_SHOW_MARKETING_STUDIO_V2Open Marketing Studio — a template gallery widget with category tabs (UGC ads, product shots, motion graphics, posters, ads, marketplace) and a preset grid the user browses and recreates from with their own product image. Use this whenever the user asks for Marketing Studio or wants marketing assets from a template/preset catalog. The widget handles preset selection, inputs, generation, and result display itself — no follow-up tool calls needed. If the result is a workspace-selection error, ask the user which workspace to use, call select_workspace, then call this tool again.

Input Parameters

string ("all" | "ugc" | "product-shot" | "motion" | "ads" | "posters" | "marketplace")
Category tab to open on. Defaults to ‘all’.

Output

string
object
string
array
string
Slug: HIGGSFIELD_MCP_SHOW_MEDIASList your uploaded media files by type. Returns media IDs, URLs, and creation timestamps. Call once with the single type the user asked for (default image); do not enumerate the other types unless the user explicitly asks for them. Pass media IDs as value in the medias array of generation tools. Paginated: if next_cursor is not null, pass it as cursor to get the next page.

Input Parameters

integer
Number of results per page
string ("image" | "video" | "audio")
Media type to list. Defaults to image.
number
Pass next_cursor from previous response to get next page

Output

string
array
Array of uploaded media files. Absent on error.
string ("image" | "video" | "audio")
The media type this listing is for (echoes the request’s type).
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Pass as cursor to get next page. Null if no more results.
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
Slug: HIGGSFIELD_MCP_SHOW_PLANS_AND_CREDITSOpen the single combined pricing widget for everything billing-related. The widget has two tabs the user can switch between: Upgrade Plan (Plus + Ultra, monthly + annual subscription cards) and Top-up Credits (one-time credit packs of 500 / 1,000 / 2,000 / 4,000 credits). Cards include feature lists, 7-Day Unlimited highlights, and 365-Day Unlimited blocks pulled from the live pricing config. Each plan card and credit pack has a CTA that links directly to the relevant Stripe or Higgsfield checkout/setup URL — no separate tool is needed to mint checkouts. For every billing request, the text response and assistant_response are intentionally short, user-facing sales copy with checkout URLs wrapped as action-specific Markdown links such as [Go to Checkout](url), [Higgsfield Upgrade](url), [Higgsfield Credit Top-up](url), [Higgsfield Auto-refill](url), [Higgsfield Team Top-up](url), or [Higgsfield Team Auto-refill](url); relay that response verbatim instead of summarizing, saying only that the widget opened, or listing options without links. If the user asks to buy credits or they are out of credits, first push auto-refill when auto_refill_purchase_link is present, then show credit_purchase_links. If the user asks to upgrade or a minimum plan is required, show plan_purchase_links. Pass intent='auto_refill' for out-of-credits recovery, intent='topup' for one-time credit packs, intent='upgrade' for plan upgrades, or intent='trial' when the user specifically asks for the free trial so the response is ordered for that purchase path. FREE TRIAL: when free_trial is present in the response, the user is eligible for a 3-day $0 Plus trial with MCP-only credits — the widget shows it and the text response leads with it. In text-only clients ALWAYS relay free_trial.compliance_note verbatim (MCP-only, card required, automatic charge after the trial unless cancelled, how to cancel by saying ‘cancel auto-renewal’). When free_trial is absent, NEVER speculate about trial eligibility or mention fraud/abuse checks — present the paid plans neutrally. When initial_view='trial_upgrade', the user’s trial credits are exhausted: relay the numbered upgrade options plus the renewal reminder, and mention that saying ‘cancel auto-renewal’ stops the upcoming charge while keeping trial access. To cancel the trial’s auto-renewal, call cancel_trial_auto_renewal instead of this tool. Use this tool for ANY of these requests: plans, pricing, subscriptions, upgrade options, comparing tiers, buying credits, topping up credits, refilling credits, credit packs. Do not look for separate show_plans or show_credit_topups tools — both have been merged into this one. Returns already_subscribed: true when the workspace is already on a paid plan; the widget hides the Upgrade tab in that case and shows only credit top-ups. Team-plan workspaces: workspace_kind field indicates the context. When workspace_kind='team_owner', the widget renders team-specific Top-up and Auto-refill UIs and emits team_purchase_links (two links: team_top_up and team_auto_refill) that deeplink to the team billing modals on higgsfield.ai — relay both Markdown links in the text response. When workspace_kind='team_member', no purchase links are returned; the widget shows a read-only notice and the text response tells the user only the workspace owner can buy credits or change auto-refill. Do not invent purchase links for members.

Input Parameters

string ("upgrade" | "topup" | "auto_refill" | "trial" | "general")
Purchase path to prioritize in the widget and text fallback. Use auto_refill for out-of-credits recovery, topup for one-time credit packs, upgrade for minimum-plan errors or plan changes, trial when the user specifically asks for the free trial, and general for pricing comparison.

Output

string
array
Subscription plan cards with rich pricing-config data merged in. Empty when the user is on a paid plan.
array
One-time credit top-up packages. Empty when the user is on the free plan.
object
Free trial offer (see kind for what it starts). Present ⇔ the user is eligible. When absent, do NOT speculate about why — keep copy neutral (never mention eligibility, fraud, or abuse checks).
string
MCP server HTTP request ID for support/debugging.
object
Team-owner config: credit price, deeplink URLs, quick-select chips, auto-refill field limits, workspace name. Only present when workspace_kind=team_owner.
string
Credits auto-refill settings. Drives the auto-refill subtab inside the top-up panel; only shown when is_eligible=true.
string ("upgrade" | "topup")
Tab the widget should select first for this tool invocation.
object
Team-member context: read-only workspace metadata. Only present when workspace_kind=team_member.
string
Direct URL for the primary checkout/setup action. Agents MUST show this exact link in text-only clients.
string
Plan type the workspace is currently on, when already_subscribed=true.
string ("plans" | "trial" | "trial_upgrade")
Layout the widget opens with: plans (Plus/Ultra grid, plus the trial section when free_trial is present), trial (standalone trial card), trial_upgrade (trial credits exhausted — upgrade view).
object
Current MCP free-trial state, when the status endpoint responded.
string
CTA label for checkout_url.
Flattened direct purchase/setup links. Agents MUST relay relevant URLs when the client does not render the billing widget.
string
Personalized seller-style headline that explains the recommended purchase path.
string ("individual" | "team_owner" | "team_member")
Workspace context: individual private workspace, team-plan workspace owner, or team-plan member. Drives both widget UI and which links are returned.
object
STATIC Free/Plus/Ultra comparison table for the trial-exhausted view.
string
Action-oriented CTA label for the primary purchase link.
string
Short promoter-style copy suitable for text-only MCP clients.
number
Number of days extra credits remain valid after purchase.
boolean
True if the workspace already has a paid plan.
string
Ready-to-send promoter-style purchase response with checkout URLs formatted as action-specific Markdown links, e.g. Go to Checkout, Higgsfield Upgrade, Higgsfield Credit Top-up, or Higgsfield Auto-refill. Agents should relay this in text-only clients or when the widget location is unclear.
Direct subscription upgrade checkout links.
Team-plan owner deeplinks (top-up + auto-refill). Only present when workspace_kind=team_owner.
Direct $0 trial checkout link, when the user is eligible.
string
Checkout/setup URL for credits auto-refill. Render the setup banner only when this URL is present.
Direct one-time credit-pack checkout links.
Best single checkout/setup link for the requested intent. For credit recovery this prioritizes auto-refill when eligible, then one-time top-ups.
string
Short rationale for why this offer is being shown for the user’s current plan/eligibility.
Direct auto-refill setup link, when available.
boolean
Presentation-only gate derived from the trial kind (offer or existing trial). False/absent keeps every legacy widget branch.
string
Largest annual discount percentage to show near the annual billing toggle.
Slug: HIGGSFIELD_MCP_SHOW_REFERENCE_ELEMENTSElements widget — reusable characters / environments / props per workspace. Actions:
  • list (default; paginated by created_at DESC, use cursor from prev next_cursor).
  • get (default when element_id is set).
  • create: pass medias[] as { id, url, type: 'media_input' | 'image_job' }. Upload first via media_upload → PUT bytes → media_confirm. category='auto' lets the server classify (use explicit only on user ask). Omit name to auto-derive (per-workspace unique, collisions get a numeric suffix). Returns synchronously.
AMBIGUITY GUARD vs Soul — user wants a reusable face of one specific person (digital twin / ‘my avatar’ / identity) without a chosen path: do NOT silently create; ask:
  1. Element (this tool action=create) — instant, single image, MULTIPLE references per generation, works with Nano Banana Pro / 2, GPT Image 2, Seedream 4.5 / 5 lite, Cinema Studio Image 2.5, Cinema Studio Video 2 / 3.0, Seedance 2.0, Kling 3.0. NOT for Soul V2 / Cinema.
  2. Soul (show_characters action=train) — 5-20 photos, ~10 min, ONE person, Soul V2 / Cinema only. Skip the question → Elements on: >1 character/subject in one shot (Soul can’t), non-person subject, single image, mention of Nano Banana / Seedream / Kling / Cinema Studio, instant result. Skip → Soul on: ‘train’ / ‘digital twin’ / ‘identity’, or 5+ photos of one person for solo outputs.
USAGE IN GENERATION (internal — never explain to user): Embed <<<element_id>>> inside params.prompt of generate_image / generate_video. Backend auto-injects the image and rewrites to @element_name. Multiple placeholders per prompt OK. Example: "Cinematic portrait of <<<UUID>>> on a rooftop", "<<<A>>> handing coffee to <<<B>>> in a Paris cafe".SUPPORTED MODELS (params.model = machine name, friendly in parens):
  • Image: nano_banana_pro (Nano Banana Pro), nano_banana_2 (Nano Banana 2), gpt_image_2 (GPT Image 2), seedream_v4_5 (Seedream 4.5), seedream_v5_lite (Seedream 5.0 lite), cinematic_studio_2_5 (Cinema Studio Image 2.5).
  • Video: cinematic_studio_video_v2 (Cinema Studio Video 2), cinematic_studio_3_0 (Cinema Studio Video 3.0), seedance_2_0 (Seedance 2.0), kling3_0 (Kling 3.0 — REQUIRES a start_image in params.medias; element placeholder alone won’t trigger reference usage). Map friendly→machine silently. Other models silently ignore the placeholder.
USER-FACING STYLE: use friendly model names only; never expose machine names, <<<UUID>>> syntax, params.model / params.prompt, generate_image / generate_video, or ‘job_set_type’. Reference elements by name, never id.GUARDS:
  • @name form does NOT work in tool calls — only <<<UUID>>> in params.prompt.
  • Do NOT put element ids in params.medias / params.input_images — placeholder handles injection.
  • kling3_0 only honors reference elements when an explicit start_image is provided in params.medias. If the user wants Kling 3.0 with an element but hasn’t supplied a start frame, ask for one (upload via media_upload → PUT bytes → media_confirm, or pick a prior generation) before calling generate_video. Without a start_image, pick another video model from the list.
  • Only status: completed elements are usable; skip processing / ip_checking / failed / kling_failed / nsfw.

Input Parameters

string
[action=create] Element name, max 32 chars. Spaces are normalised to ’-’. If omitted, the server derives a name from the media.
integer
[action=list] Number of elements per page (1-100).
string ("list" | "get" | "create")
Operation mode. Defaults to get if element_id is set, otherwise list.
number
[action=list] Pass next_cursor from a previous response to get the next page.
array
[action=create] Image references. Required. URLs must be https (private/loopback hosts rejected); normally Higgsfield upload URLs returned by media_upload → PUT bytes → media_confirm.
string ("auto" | "character" | "environment" | "prop")
[action=create] auto lets the server classify from the first images. Use a specific category only if the user is explicit. Defaults to auto.
string
[action=get] Fetch a single reference element by id.
string
[action=create] Optional free-form description, stored as-is.

Output

string
array
Reference elements. Single-element when action=get, otherwise the page from action=list.
object
[action=create] The created reference element.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
[action=list] Pass as cursor to fetch the next page. Null when no more pages.
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
Slug: HIGGSFIELD_MCP_SYNC_AGENTSSync Agents — imports the user’s user-authored Skills and a personality dump from the current host LLM into Higgsfield. One trigger, one upload, one final confirmation.Calling modes:
  1. message: "/sync-agents" — server returns a short ack in content[0].text plus an assistant-only directive containing a self-contained Python upload script (pre-wired with a one-time presigned POST URL scoped to one per-user prefix). Print the ack verbatim. Then follow the directive: enumerate user-authored skills + synthesize personality.md into /tmp/profile-import/{skills,personality}/, run the script in your code-execution sandbox, capture its single-line JSON summary, and call this tool again with that summary as message.
  2. message: "<script summary JSON>" — server reads the uploaded .md files, parses each, and upserts the user’s Skill rows. Returns a one-line confirmation summarising counts (e.g. “Imported 3 skill(s) (2 new, 1 updated) · personality queued for save to your memory.”). Print that confirmation verbatim to the user. Also pass host on this call — your own runtime identifier (e.g. claude_ai, claude_code, codex, cursor); it is stamped on every newly imported skill’s import_origin so the marketplace can attribute origin per host.
No polling, no chains. Each call returns synchronously.

Input Parameters

string ("claude_ai" | "claude_code" | "codex" | "cursor" | "windsurf" | "hermes" | "openclaw" | "other")
required
Identifier of the host LLM/runtime you are running inside. Stamped on each imported skill’s import_origin column so the marketplace can attribute imports per host. Self-classify honestly: claude_ai (Claude.ai web/desktop), claude_code (Claude Code CLI), codex (OpenAI Codex / ChatGPT code interpreter), cursor, windsurf, hermes (Higgsfield hermes-agent), openclaw (Higgsfield OpenClaw), or other if none fit. Do not invent values — the enum is closed; pick other when uncertain.
string
required
Either the literal trigger /sync-agents (server replies with an assistant-only Python upload script wired to a per-user S3 presigned-POST session — print only the short ack to the user, then run the script), or the JSON summary the script prints when it finishes (server finalises the import by parsing every uploaded .md into the user’s Skill catalog).
Slug: HIGGSFIELD_MCP_TIKTOK_ACCOUNTSList the user’s connected TikTok accounts. Returns each account’s connector_id (needed by other tiktok_* tools) and status. active accounts are ready; error accounts need tiktok_reconnect; no accounts ⇒ offer tiktok_connect. Read-only.

Output

string
array
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
Slug: HIGGSFIELD_MCP_TIKTOK_CONNECTStart connecting the user’s TikTok account. Returns an authorize_url — show it to the user as a link; they open it in a browser, approve access on TikTok, and land on a confirmation page. Afterwards call tiktok_accounts to verify the account became active. The URL expires in ~10 minutes. If an account already exists in error status, use tiktok_reconnect instead.

Input Parameters

string
Only when connecting a SECOND account: a distinct label, e.g. “tiktok-brand”. Default “tiktok”.

Output

string
string
The authorize URL is valid until this time (~10 minutes).
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
string
Show this URL to the user as a clickable link.
Slug: HIGGSFIELD_MCP_TIKTOK_MUSIC_TUNEOpen the tuning editor for one Commercial Music Library track the user already picked (via tiktok_music_trending): trim start/end and set track/original volumes. Pass the same genre/country_code/date_range filters that were used when the track was found, or the lookup may miss. The user copies the final configuration from the editor and pastes it into the chat; pass those values to tiktok_publish. Read-only.

Input Parameters

string
Same filter the track was found with, if any.
string ("1DAY" | "7DAY" | "30DAY" | "90DAY")
string
required
Active TikTok account from tiktok_accounts.
string
string
required
The picked track’s id (from tiktok_music_trending / the user’s paste).

Output

string
object
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
Slug: HIGGSFIELD_MCP_TIKTOK_PREPARE_PUBLISHStep 1 of publishing to TikTok. Validates the media and TikTok account, creates a publish session, and returns what the user must review and choose (preview, privacy options, required declarations, confirmations). The media URL must be a Higgsfield-hosted asset (TikTok requires a verified source domain). Then collect the user’s choices and call tiktok_publish. mode=DIRECT_POST posts to the profile; mode=UPLOAD_TO_DRAFT saves to the user’s TikTok drafts. MEDIA LIMITS — check before calling, and convert or downscale locally if a file does not comply; a rejected file costs a full convert-and-re-upload round trip, and TikTok rejects some files only asynchronously, after the post was submitted. Photos: JPEG or WebP only (PNG is rejected by TikTok, and Higgsfield image generation emits PNG — convert first), each at most 20 MB, resolution must fit within 1920x1080 or 1080x1920, up to 35 images. Videos: MP4, WebM or MOV, at most 1 GB, 3-600 seconds, at least 360 px on both sides, 23-60 FPS.

Input Parameters

string ("DIRECT_POST" | "UPLOAD_TO_DRAFT")
required
string
Caption / title.
boolean
Prefill — only if the user already stated whether the media is AI-generated.
string
Required for VIDEO. Must be a Higgsfield-hosted asset URL.
boolean
Prefill — only if the user already stated it.
string ("VIDEO" | "PHOTO")
required
string
boolean
Prefill — only if the user already stated it.
string
required
Active TikTok account from tiktok_accounts.
array
Required for PHOTO. Higgsfield-hosted image URLs.
boolean
Prefill — only if the user already stated it.
string ("PUBLIC_TO_EVERYONE" | "MUTUAL_FOLLOW_FRIENDS" | "FOLLOWER_OF_CREATOR" | "SELF_ONLY")
Prefill for the publish form — pass ONLY if the user already stated it explicitly.
integer
object
Prefill — only if the user already stated it.

Output

string
string
object
Choices the user already made in chat; the publish form starts from these.
string
string
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Echoed for the publish-form widget’s server calls.
object
string
string
string
string
array
array
string
Slug: HIGGSFIELD_MCP_TIKTOK_PUBLISHStep 2 of publishing. Call only after tiktok_prepare_publish and after collecting the user’s explicit choices and confirmations. Pass the publish_session_id from prepare (the media is locked to it — do not resend URLs). Set every flag listed in the prepare response’s required_confirmations to true; these represent real user consent (AIGC/branded-content/music/privacy). Optionally attach a commercial track via music_sound_id from tiktok_music_trending (DIRECT_POST only). Returns a publish_id for tiktok_publish_status. PUBLISH QUOTAS per account, enforced before TikTok is called: at most 5 posts per minute and 13 posts per 24 hours, both rolling (TikTok’s own ceiling is 6/minute and 15/day). A rejection returns code=cadence_burst or cadence_daily plus retry_after_seconds — wait that long instead of retrying, since retrying sooner only earns another rejection. Failed attempts and drafts do not consume quota; a post TikTok accepted does. Duration, frame size and frame rate are measured from the media file itself by tiktok_prepare_publish, before a publish slot is spent — there is no duration argument, never ask the user for one. music_sound_volume, video_original_sound_volume, music_sound_start and music_sound_end apply only together with music_sound_id and only to videos; without a track, or on a photo post, they are ignored. MEDIA LIMITS — check before calling, and convert or downscale locally if a file does not comply; a rejected file costs a full convert-and-re-upload round trip, and TikTok rejects some files only asynchronously, after the post was submitted. Photos: JPEG or WebP only (PNG is rejected by TikTok, and Higgsfield image generation emits PNG — convert first), each at most 20 MB, resolution must fit within 1920x1080 or 1080x1920, up to 35 images. Videos: MP4, WebM or MOV, at most 1 GB, 3-600 seconds, at least 360 px on both sides, 23-60 FPS.

Input Parameters

string ("DIRECT_POST" | "UPLOAD_TO_DRAFT")
required
string
boolean
Set true for AI-generated/edited media (AIGC disclosure).
boolean
string ("VIDEO" | "PHOTO")
required
string
boolean
string
required
boolean
string ("PUBLIC_TO_EVERYONE" | "MUTUAL_FOLLOW_FRIENDS" | "FOLLOWER_OF_CREATOR" | "SELF_ONLY")
Required for DIRECT_POST; pick from prepare’s privacy_level_options.
boolean
string
Commercial Music Library track to attach: song_clip_id from tiktok_music_trending. DIRECT_POST only — drafts don’t keep music. Mutually exclusive with auto_add_music.
boolean
required
integer
Track trim end in milliseconds. Defaults to the video duration. VIDEO only.
integer
Track trim start in milliseconds (65000 starts the track at 1:05). Defaults to the track beginning. VIDEO only.
boolean
required
integer
Track volume 0-100. Defaults to 50. VIDEO only.
string
required
From tiktok_prepare_publish.
boolean
integer
Original video audio volume 0-100. Defaults to 50 (0 mutes the user’s own audio). VIDEO only.
object
DIRECT_POST: if enabled, at least one of your_brand / branded_content must be true.
boolean
boolean
boolean
Required when branded_content is disclosed.
boolean
boolean

Output

string
string
string
Pass to tiktok_publish_status.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
Slug: HIGGSFIELD_MCP_TIKTOK_PUBLISH_STATUSStep 3 of publishing. Fetch processing status for a publish_id returned by tiktok_publish. TikTok may take a few minutes to process before the post is live. Read-only.

Input Parameters

string
required
From tiktok_publish.
string
required

Output

string
string
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
Slug: HIGGSFIELD_MCP_TIKTOK_RECONNECTRe-run the TikTok OAuth for an existing connector in error status (expired/revoked access). Returns a fresh authorize_url — show it to the user as a link, then verify with tiktok_accounts.

Input Parameters

string
required
The connector to reconnect, from tiktok_accounts.

Output

string
string
The authorize URL is valid until this time (~10 minutes).
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
string
Show this URL to the user as a clickable link.
Slug: HIGGSFIELD_MCP_TRANSACTIONSList the user’s credit transactions (spend/refund/grant/deduct), newest first. Paginated: if next_cursor is not null, pass it as cursor to get the next page.

Input Parameters

integer
Number of transactions per page (1-100)
integer
Pass next_cursor from the previous response to fetch the next page

Output

string
array
Credit transactions on this page
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Pass as cursor to fetch the next page. Null if no more pages.
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
Slug: HIGGSFIELD_MCP_UPSCALE_IMAGEUpscale and enhance an existing image. Use this when the user asks to upscale, enhance, or increase the resolution of an image to 2K/4K. This tool does not use prompt or count. Provider selects the upscale backend; currently only ‘bytedance’ is supported (the default). You MUST pass the source image’s width and height in pixels (the caller supplies them; the server does not infer them). Set params.get_cost=true to preflight credits (flat cost) without submitting a job.

Input Parameters

object
required
Image upscale parameters. prompt and count are not supported.

Output

object
Populated only when the tool was called with get_cost: true. No job was submitted.
string
object
array
string
object
Suggested follow-up tool call (e.g. show_marketing_studio fetch) attached to some marketing error results.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
object
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Direct URL for the primary checkout/setup action. Agents MUST show this exact link in text-only clients.
object
NO JOB WAS SUBMITTED. The caller has free unlimited generations that cover this model, and nobody has said whether to spend them. Ask the user, then call the same tool again with use_unlim: true (free) or use_unlim: false (credits). Do not pick for them.
string ("show_plans_and_credits" | "media_import_url")
Canonical recovery tool for host/client routing.
string
CTA label for checkout_url.
All direct purchase/setup links returned for billing recovery.
string
Personalized seller-style headline for the recovery offer.
string
Short reason for opening the recovery tool.
string
Live brand kit status when a generation was rejected because the kit is not ready yet.
string
Action-oriented CTA label for the primary recovery link.
string
Short promoter-style recovery copy.
string
Ready-to-send promoter-style billing response. Generation tools prefer recovery_tool instead; billing tools use this for final sales copy with checkout URLs formatted as action-specific Markdown links, e.g. Go to Checkout, Higgsfield Upgrade, Higgsfield Credit Top-up, or Higgsfield Auto-refill.
object
Set when the server auto-picked an avatar because product_ids were passed without avatars/avatar_ids (Marketing Studio video).
string
Arguments for the recovery tool.
string ("upgrade" | "topup" | "auto_refill" | "trial" | "general")
Purchase path selected for this recovery response.
Direct subscription upgrade links.
Direct one-time credit-pack links.
Best single checkout/setup link for this recovery path. Out-of-credits recovery prioritizes auto-refill when eligible, then one-time top-ups.
string
Short rationale for why this recovery offer is being shown.
object
Context for media import recovery before retrying a generation.
object
Optional context explaining why the billing recovery response was attached.
Direct auto-refill setup link.
Slug: HIGGSFIELD_MCP_UPSCALE_VIDEOUpscale and enhance an existing video. Use this when the user asks to upscale, enhance, sharpen, denoise, restore, or convert a video to higher resolution. This tool does not use prompt or count, and does not support cost preflight. Choose a provider: ‘bytedance’ (preset-based, target 1080p/2K/4K — you MUST pass the source video width/height in pixels and may set fps to 24/30/60) or ‘topaz’ (Topaz Video, aspect-ratio based, target 1080p/2160p — no source dimensions needed).

Input Parameters

string
required
Video upscale parameters. Set provider to ‘bytedance’ or ‘topaz’. prompt, count and get_cost are not supported.

Output

object
Populated only when the tool was called with get_cost: true. No job was submitted.
string
object
array
string
object
Suggested follow-up tool call (e.g. show_marketing_studio fetch) attached to some marketing error results.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
object
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Direct URL for the primary checkout/setup action. Agents MUST show this exact link in text-only clients.
object
NO JOB WAS SUBMITTED. The caller has free unlimited generations that cover this model, and nobody has said whether to spend them. Ask the user, then call the same tool again with use_unlim: true (free) or use_unlim: false (credits). Do not pick for them.
string ("show_plans_and_credits" | "media_import_url")
Canonical recovery tool for host/client routing.
string
CTA label for checkout_url.
All direct purchase/setup links returned for billing recovery.
string
Personalized seller-style headline for the recovery offer.
string
Short reason for opening the recovery tool.
string
Live brand kit status when a generation was rejected because the kit is not ready yet.
string
Action-oriented CTA label for the primary recovery link.
string
Short promoter-style recovery copy.
string
Ready-to-send promoter-style billing response. Generation tools prefer recovery_tool instead; billing tools use this for final sales copy with checkout URLs formatted as action-specific Markdown links, e.g. Go to Checkout, Higgsfield Upgrade, Higgsfield Credit Top-up, or Higgsfield Auto-refill.
object
Set when the server auto-picked an avatar because product_ids were passed without avatars/avatar_ids (Marketing Studio video).
string
Arguments for the recovery tool.
string ("upgrade" | "topup" | "auto_refill" | "trial" | "general")
Purchase path selected for this recovery response.
Direct subscription upgrade links.
Direct one-time credit-pack links.
Best single checkout/setup link for this recovery path. Out-of-credits recovery prioritizes auto-refill when eligible, then one-time top-ups.
string
Short rationale for why this recovery offer is being shown.
object
Context for media import recovery before retrying a generation.
object
Optional context explaining why the billing recovery response was attached.
Direct auto-refill setup link.
Slug: HIGGSFIELD_MCP_VIDEO_ANALYSIS_CREATEStart a scene-by-scene analysis of a video. Provide EXACTLY ONE of: (a) video_input_id — UUID of a video the user has uploaded via media_upload/media_confirm, or (b) youtube_url — a YouTube link (youtube.com / youtu.be hosts only). Returns immediately with status=‘queued’; poll video_analysis_status until status=‘completed’. Processing typically takes 3-5 minutes on average. IMPORTANT: warn the user up front that the longer the video, the less accurate the scene-by-scene analysis becomes — short clips give the most reliable results.

Input Parameters

string
HTTPS YouTube video URL on youtube.com, www.youtube.com, m.youtube.com, or youtu.be.
string
UUID of the uploaded source video (the media_id returned by the upload tool).

Output

object
required
Slug: HIGGSFIELD_MCP_VIDEO_ANALYSIS_JOBSList the user’s video analyses in the current workspace, newest first. Paginate by passing the previous response’s cursor.

Input Parameters

integer
Page size.
string
Pagination cursor — unix timestamp of created_at from the previous page (advances backwards in time). Omit for the first page.

Output

array
required
string
required
number
required
Slug: HIGGSFIELD_MCP_VIDEO_ANALYSIS_STATUSGet the status and result of a video analysis. Poll this after video_analysis_create until status=‘completed’ (scenes populated) or ‘failed’ (fail_reason populated). Analyses typically finish in 3-5 minutes — poll accordingly every 30-60 seconds.

Input Parameters

string
required
UUID returned by video_analysis_create or video_analysis_jobs.

Output

object
required
Slug: HIGGSFIELD_MCP_VIRALITY_PREDICTORVirality Predictor predicts a video’s virality potential, engagement, attention, audience response, retention risk, hook strength, and creative performance with an interactive dashboard. Use when the user asks whether a video can go viral or wants creative-performance analysis. Create starts analysis from a confirmed uploaded video or completed generated video; preview re-opens an existing dashboard.

Input Parameters

string ("create" | "preview")
required
create starts Virality Predictor analysis; preview re-opens an existing dashboard.
object
required
Virality Predictor parameters. create uses medias; preview uses job_id.

Output

string
string
Virality Predictor model identifier rendered by the UI resource.
string
Created or previewed Virality Predictor job ID; pass to action=“preview” to re-open.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
number
Suggested app polling interval in seconds. Returned for create.
Slug: HIGGSFIELD_MCP_VOICE_CHANGEReplace the spoken voice in a video with a different voice while keeping the original timing and visuals, then re-merge the new audio onto the video. Use this when the user asks to change, swap, or revoice the speaker in a clip. Pass video_id for the source video (a confirmed uploaded media_id or a completed video generation job_id) and voice_id for the target voice. voice_type selects whether voice_id is a built-in preset voice (‘preset’) or a workspace reference element (‘element’). This tool does not use prompt or count; output dimensions are taken from the source video automatically.

Input Parameters

object
required
Voice change parameters.

Output

object
Populated only when the tool was called with get_cost: true. No job was submitted.
string
object
array
string
object
Suggested follow-up tool call (e.g. show_marketing_studio fetch) attached to some marketing error results.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
object
string
Upgrade URL. If present, you MUST show this exact upgrade link to the user so they can upgrade to continue working.
string
Direct URL for the primary checkout/setup action. Agents MUST show this exact link in text-only clients.
object
NO JOB WAS SUBMITTED. The caller has free unlimited generations that cover this model, and nobody has said whether to spend them. Ask the user, then call the same tool again with use_unlim: true (free) or use_unlim: false (credits). Do not pick for them.
string ("show_plans_and_credits" | "media_import_url")
Canonical recovery tool for host/client routing.
string
CTA label for checkout_url.
All direct purchase/setup links returned for billing recovery.
string
Personalized seller-style headline for the recovery offer.
string
Short reason for opening the recovery tool.
string
Live brand kit status when a generation was rejected because the kit is not ready yet.
string
Action-oriented CTA label for the primary recovery link.
string
Short promoter-style recovery copy.
string
Ready-to-send promoter-style billing response. Generation tools prefer recovery_tool instead; billing tools use this for final sales copy with checkout URLs formatted as action-specific Markdown links, e.g. Go to Checkout, Higgsfield Upgrade, Higgsfield Credit Top-up, or Higgsfield Auto-refill.
object
Set when the server auto-picked an avatar because product_ids were passed without avatars/avatar_ids (Marketing Studio video).
string
Arguments for the recovery tool.
string ("upgrade" | "topup" | "auto_refill" | "trial" | "general")
Purchase path selected for this recovery response.
Direct subscription upgrade links.
Direct one-time credit-pack links.
Best single checkout/setup link for this recovery path. Out-of-credits recovery prioritizes auto-refill when eligible, then one-time top-ups.
string
Short rationale for why this recovery offer is being shown.
object
Context for media import recovery before retrying a generation.
object
Optional context explaining why the billing recovery response was attached.
Direct auto-refill setup link.
Slug: HIGGSFIELD_MCP_WEBSITE_DBInspect the website’s database (D1 / SQLite), READ-ONLY. The website has ONE database — the live site’s real data. Pick an operation: ‘tables’ (list tables); ‘schema’ (a table’s columns — needs table); ‘rows’ (a page of rows — needs table; optional filters, order_by + order_dir, limit (default 50) + offset); ‘query’ (one read-only SELECT/WITH — needs sql). Writes and DDL are rejected.

Input Parameters

string
A single read-only SELECT/WITH statement (operation ‘query’).
integer
string
Table name. Required for ‘schema’ and ‘rows’.
integer
array
‘rows’ filters, each ‘col:op[:value]’ (eq ne gt gte lt lte like is_null).
string
string ("tables" | "schema" | "rows" | "query")
required
What to read: tables | schema | rows | query.
string ("asc" | "desc")
string
required
The website’s id (returned by create_website).

Output

string
object
The read result (shape depends on operation).
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
Slug: HIGGSFIELD_MCP_WEBSITE_REPO_ACCESSGet direct git access to a website’s repo to edit it — THE way to get the website’s code. Returns the repo URL, branch, slug, and a scoped token; clone it with the terminal tool, edit files, commit + push, then call deploy_website. Clone into a directory named after the slug so multiple websites can share the workspace. Access is scoped to your own websites — do not echo the token back to the user.

Input Parameters

string
required
The website’s id (returned by create_website).

Output

string
string
string
Scoped git token — do not echo back to the user.
string
string
string
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
Slug: HIGGSFIELD_MCP_WEBSITE_SECRETSManage a website’s SECRETS (environment variables: API keys, tokens). Set them HERE instead of hardcoding them in source. One tool, three operations: ‘set’ (store/replace — needs name + value); ‘delete’ (remove — needs name); ‘list’ (the configured secrets as a {name: value} map). A change (set OR delete) is STAGED — NOT live until the next deploy_website. Read a secret SERVER-side in website code; never ship it to the browser.

Input Parameters

string
Secret name (env var). Required for ‘set’ and ‘delete’.
string
Secret value. Required for ‘set’.
string ("set" | "delete" | "list")
required
What to do: ‘set’, ‘delete’, or ‘list’.
string
required
The website’s id (returned by create_website).

Output

string
boolean
True for set/delete — NOT live until the next deploy.
object
The configured secrets as a {name: value} map.
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
Slug: HIGGSFIELD_MCP_WEBSITE_STATUSGet the website’s deploy status — the live URL and the status of the last deploy. Use to check a deploy that returned ‘pending’, or to fetch the live URL.

Input Parameters

string
required
The website’s id (returned by create_website).

Output

string
string
object
string
MCP server HTTP request ID for support/debugging. If present, show it to the user.
array
The social-media links submitted with the contest entry.
string
The website’s community-feed listing page, when listed.
boolean
Whether the website is currently on the community feed.
boolean
Whether the website is currently entered in the app contest.