Higgsfield

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

scene_builder_3d_search_assets

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

scene_builder_3d_show_scene

Browse Higgsfield preset galleries without starting a generation. A bare preset slash command or a request to open, preview, or browse a preset only opens its widget. For supplied attachments, use input_schema from get_preset_instructions to map and upload the relevant files before opening any widget. Call get_presets exactly once with source, preset_id and initial_inputs in the exact schema fields. Do not call get_presets just to inspect the schema. Leave omitted settings to schema defaults; never reopen the detail merely to repeat default selections. Never assume one photo satisfies all requirements or guess ambiguous slot assignments. Leave missing fields in the prefilled widget for the user. Stop after opening the detail and let the user interact with it. Do not call execute_preset unless the user explicitly asks to generate, or submits with Recreate in the widget. Check execution.readiness for the supplied inputs before execution; collect missing or invalid fields instead of submitting. execution.available indicates capability, not permission; optional inputs and built-in media do not authorize generation. Readiness checks input structure, not media ownership or upload confirmation; use only confirmed media IDs. If the widget reports submitted job IDs, display and wait for those jobs without executing again. Pass query to search preset names, descriptions and types before pagination. All query words must match; omit source to search both galleries. Pass preset_id to open a published preset detail preview directly. Omit source to browse both galleries; limit applies to the complete page. source='viral' lists Viral Hub chain presets for /effects requests; source='marketing_studio' lists Marketing Studio templates: for /product use category='product-shot', for /motion use category='motion'. Use category slugs returned by this tool and pass next_cursor only when the user asks for another page.

get_presets

Read-only balance: credits, workspace plan, free generations (free_gens — Genjutsu on generate_video and Viral on execute_preset, spent with use_free_gens:true), and free-trial state (free_trial.unlim_available says whether unlimited generations can be spent). Also returns pricing_url, an informational higgsfield.ai page describing the available plans. Call it for any credits / plan / trial question or after an out-of-credits error, report the state, and show pricing_url verbatim as a plain link when the user asks about plans or has no credits left. This tool sells nothing and never in chat: it does not charge, upsell, or open a checkout.

balance

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

job_status

Clear the active workspace selection so subsequent MCP operations use the user's default private workspace. This changes selection only; it does not delete any workspace.

workspace_clear_selection

Confirm 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. OpenAI routing: use this for sandbox-created files uploaded through media_upload + sandbox_exec. Do not call it after media_upload_and_confirm; ChatGPT attachments handled by that tool are already confirmed.

media_confirm

Create a brand kit from user-provided brand data only. This does not scrape websites, fetch third-party URLs, or create checkout/purchase flows.

marketing_create_brand_kit

Create one subfolder in an existing Higgsfield media project. Use project_id returned by create_project in this conversation or explicitly supplied by the user. Omit parent_folder_id to create directly under the root. Keep using the project's default_folder_id for generation unless the user wants outputs in this subfolder; then pass its folder_id. This does not create a project or a local filesystem folder. Creation is not idempotent: do not automatically retry after a timeout or uncertain result.

create_folder

Create a Marketing Studio product from user-provided uploaded media IDs and manual metadata. This does not scrape external websites or fetch third-party URLs.

marketing_create_product_from_media

Create a private Higgsfield media project for this conversation. Call once when the conversation needs a new media project, then retain project_id, workspace_id and default_folder_id in this conversation and pass folder_id on subsequent generate_* calls. Reuse the existing project on later turns; never create one per generation or reuse another conversation's project. This does not create a chat, website or 3D scene. No starter/brief subfolder is created. Resolve workspace_id before the first call using list_workspaces (full) or workspace_list (OpenAI); use the selected workspace or ask the user when ambiguous. Repeat an uncertain request only with the original workspace_id, name, surface and idempotency_key, even if the selected workspace changes; backend replay lasts 15 minutes, not the lifetime of the chat.

create_project

Start 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_and_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.

video_analysis_create

Start 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 with checkout, edit/commit using sandbox_exec, then website_repo_access with push (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).

create_website

Delete an existing brand kit by id. This permanently removes that brand kit from Marketing Studio.

marketing_delete_brand_kit

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

deploy_website

Show one specific previous generation in a new single-result UI widget by job ID. This opens an additional widget; it does not refresh an existing one. Ordinary generate_image, generate_video, and generate_audio calls already display auto-updating widgets. Do not call this tool as their automatic follow-up, even while pending or in progress or after completion; use jobs_wait with timeout_seconds <= 15 to await completion without another widget. 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.

job_display

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

participate_in_contest

Estimate image generation credit cost without submitting a job. HTTPS image references are fetched, uploaded, and confirmed in your Higgsfield media library; repeated calls can create new uploads. Requires write access. Takes the same `params` object as generate_image: `params.model` is required; `prompt` may be omitted for a cost-only estimate.

estimate_image_cost

Estimate video generation credit cost without submitting a job. HTTPS image references are fetched, uploaded, and confirmed in your Higgsfield media library; repeated calls can create new uploads. Requires write access. Takes the same `params` object as generate_video: `params.model` is required; `prompt` and `duration` may be omitted (model defaults apply).

estimate_video_cost

Request execution of one published preset from the Viral or Marketing Studio gallery. A bare preset slash command or a request to open, preview, or browse a preset only opens its widget. For supplied attachments, use input_schema from get_preset_instructions to map and upload the relevant files before opening any widget. Call get_presets exactly once with source, preset_id and initial_inputs in the exact schema fields. Do not call get_presets just to inspect the schema. Leave omitted settings to schema defaults; never reopen the detail merely to repeat default selections. Never assume one photo satisfies all requirements or guess ambiguous slot assignments. Leave missing fields in the prefilled widget for the user. Stop after opening the detail and let the user interact with it. Do not call execute_preset unless the user explicitly asks to generate, or submits with Recreate in the widget. Check execution.readiness for the supplied inputs before execution; collect missing or invalid fields instead of submitting. execution.available indicates capability, not permission; optional inputs and built-in media do not authorize generation. Readiness checks input structure, not media ownership or upload confirmation; use only confirmed media IDs. If the widget reports submitted job IDs, display and wait for those jobs without executing again. Check execution.available in the preset detail before calling. Unavailable execution returns an error without submitting a job. Use get_presets to obtain the published preset_id and source; do not invent either value. A successful submission returns final job_ids; a preset may produce multiple outputs. Use job_display for one job, jobs_wait and show_generation_by_ids for multiple jobs. Preset-specific inputs are a free-form object; their requirements are defined by the selected preset, not by this tool schema.

execute_preset

Show the faceless channel presets (CMS-managed catalog). Returns preset ids, names, and preview media. When the user picks one, resolve it with resolve_faceless_channel_preset to get the style reference media_id for generations.

get_faceless_channel_presets

Generate speech/voice audio (text-to-speech). A successful submission returns job IDs; cost preflight and unlim_choice submit no job. Call it directly with the default model `seed_audio` (Seed Audio 1.0 by ByteDance) unless the user or an active skill requires a different engine. `seed_audio` needs an exact `voice_id` + `voice_type` pair ('preset' for a built-in voice, 'element' for one of the user's own). If either value is missing, call `list_voices` as the only tool in that turn so the user can choose. The picker returns the selected pair in a new user turn; continue the pending narration immediately with this tool using that pair. Never invent a voice_id. Optional tuning: `format`, `sample_rate`, `speech_rate` (-50..100), `loudness_rate` (-50..100), `pitch_rate` (-12..12). 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. Use `models_get` / `models_search` to inspect a model's parameters. This tool only generates speech: it cannot generate music or sound effects — decline general music or sound-effect requests rather than substituting a speech model. All arguments go inside the single `params` object; `params.model` and `params.prompt` are required. `get_cost:true` returns the credit cost without submitting a job. This tool already displays its submitted jobs in an auto-updating generation widget, including while pending or in progress. Do not follow it with job_display, show_generations, or show_generation_by_ids merely to show or refresh the same results, before or after completion. To await completion, use jobs_wait with timeout_seconds <= 15; it does not open another widget. Use a separate display only when the user explicitly requests one or the workflow requires a distinct preview or approval. Headless generate_*_batch and execute_preset workflows follow their own display instructions. On a transport timeout the submission outcome may be unknown: do not automatically resubmit. Reuse returned job IDs and retry only after the original outcome is known.

generate_audio

Submit 1-6 independent audio generations in parallel without opening a widget. Each requests[] item accepts generation params with count fixed to 1 and no get_cost, creates one job on successful submission, 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 8. 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 24 jobs; never use show_generations or call job_display once per job. A partial failure or timeout does not make the whole batch safe to retry: keep returned job IDs and resolve unknown submission outcomes before retrying affected items.

generate_audio_batch

Generate an image. A successful submission returns job IDs; a choice or rejected request submits no job. For credit preflight use `estimate_image_cost` first; HTTPS image references are imported into your media library. Call this directly as the first tool call of the turn with the default model `gpt_image_2_5` for ordinary generation, photorealistic images, typography, and reference-based editing. Consult `models_recommend`, `models_search`, `models_list`, or `models_get` only when the user asks to pick or compare models, or you need `aspect_ratios`, `parameters`, or `medias[].roles` for reference inputs. Reference media can be uploaded media UUIDs from `media_upload_and_confirm`, completed generation job UUIDs, or authorized HTTPS image URLs such as user-provided file download URLs; the server imports HTTPS images into Higgsfield and confirms them automatically. For character/avatar requests use image generation directly; there is no reusable character-training flow here. All arguments go inside the single `params` object — `params.model` is required, `params.prompt` holds the text description, and model-specific parameters are additional keys of `params`. Server returns `adjustments` for fallbacks; invalid declared-param values return a structured error. This tool already displays its submitted jobs in an auto-updating generation widget, including while pending or in progress. Do not follow it with job_display, show_generations, or show_generation_by_ids merely to show or refresh the same results, before or after completion. To await completion, use jobs_wait with timeout_seconds <= 15; it does not open another widget. Use a separate display only when the user explicitly requests one or the workflow requires a distinct preview or approval. Headless generate_*_batch and execute_preset workflows follow their own display instructions. On a transport timeout the submission outcome may be unknown: do not automatically resubmit. Reuse returned job IDs and retry only after the original outcome is known.

generate_image

Submit 1-6 independent image generations in parallel without opening a widget. Each requests[] item accepts generation params with count fixed to 1 and no get_cost, creates one job on successful submission, 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 8. 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 24 jobs; never use show_generations or call job_display once per job. A partial failure or timeout does not make the whole batch safe to retry: keep returned job IDs and resolve unknown submission outcomes before retrying affected items.

generate_image_batch

Generate a video; this submits a job. For credit preflight use `estimate_video_cost`; HTTPS image references are imported into your media library. 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; reserve ad-multiplier for explicitly requested independent edited variants. Pass images with role `image` and exactly one source/driving video with role `video`. Do NOT call this for 'ad multiplier', 'multiply my video/ad', or multiple edits of one 4-30 second clip; use the `ad-multiplier` skill. Defaults: `seedance_2_5` for general video, `kling3_0` for multi-shot, audio, or motion transfer, and `minimax_h3` for 2K keyframes or mixed references. Call model discovery only to compare models or inspect parameters/media roles. References may be uploaded media UUIDs, completed job UUIDs, or authorized HTTPS image URLs. For image-to-video use the model's image role, usually `start_image` or `image`, not `video`. Use Marketing Studio product tools for product IDs and list hooks/settings before using their IDs. Put everything in `params`; `params.model` is required and `params.prompt` contains the brief. Apply returned adjustments; invalid values return a structured error. FREE GENJUTSU RUN: balance / models_list report free_gens; when the user asks to use a free generation on a Genjutsu model, pass use_free_gens:true (480p/720p, one output) — it is refused, never billed, when it does not apply. This tool already displays its submitted jobs in an auto-updating generation widget, including while pending or in progress. Do not follow it with job_display, show_generations, or show_generation_by_ids merely to show or refresh the same results, before or after completion. To await completion, use jobs_wait with timeout_seconds <= 15; it does not open another widget. Use a separate display only when the user explicitly requests one or the workflow requires a distinct preview or approval. Headless generate_*_batch and execute_preset workflows follow their own display instructions. On a transport timeout the submission outcome may be unknown: do not automatically resubmit. Reuse returned job IDs and retry only after the original outcome is known.

generate_video

Submit 1-6 independent video generations in parallel without opening a widget. Each requests[] item accepts generation params with count fixed to 1 and no get_cost, creates one job on successful submission, 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 8. 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 24 jobs; never use show_generations or call job_display once per job. A partial failure or timeout does not make the whole batch safe to retry: keep returned job IDs and resolve unknown submission outcomes before retrying affected items.

generate_video_batch

Return the Higgsfield account represented by this connection's authenticated credentials. The opaque id stays the same across token refresh, reconnection, scope upgrades, and changes to email or selected workspace. Does not select or switch accounts.

get_profile

Read-only fetch of one existing brand kit by id. Does not create, update, delete, or scrape websites.

marketing_get_brand_kit

Read-only fetch of one generation model's constraints, parameters, media roles, aspect ratios, and durations.

models_get

Resolve a named Higgsfield preset or command and read its instructions without executing it. Entries include image/video recipes, generation workflows such as /genjutsu, and setup instructions such as /use-after-effects and /use-blender. For an explicit slash invocation, resolve the exact token before selecting tools or requesting media. Omit preset to list bundled recipes and commands. Use get_presets for Viral and Marketing Studio browsing (/effects, /product, /motion); a resolved gallery entry supplies its input schema and exact detail lookup. Recipes such as /hero-shot and /reel-cover supply their generation workflow. Setup commands and their references supply instructions for the required runtime; loading them does not install software, connect an editor, or submit jobs. When no entry matches, the response says to infer the task from the token and the request and carry it out with ordinary tools; do not report the command as missing or ask the user to pick another one.

get_preset_instructions

Read-only list of Marketing Studio brand kits. Does not scrape websites, create kits, update kits, or delete kits.

marketing_list_brand_kits

Read-only list of DTC Ads image ad-format presets. Does not create or modify image styles.

marketing_list_ad_formats

List direct subfolders of a Higgsfield media project or an explicit parent_folder_id. Use a project_id from list_projects, create_project or the user. Search matches child names under that parent, not the entire tree. Returns folder_id values for subsequent generation destinations and the actual project workspace even for an empty page. Does not list local directories or create folders. Continue with cursor and the same original workspace, project, parent and search; use has_more, not item count, to detect completion.

list_folders

Read-only list of user and preset Marketing Studio avatars. Does not create or modify avatars.

marketing_list_avatars

Read-only list of existing Marketing Studio setup hooks. Use returned ids as hook_id in generate_video. Does not create, update, or delete hooks.

marketing_list_hooks

Read-only list of Marketing Studio products. Does not fetch websites, create products, or modify products.

marketing_list_products

Read-only list of existing Marketing Studio setup settings. Use returned ids as setting_id in generate_video. Does not create, update, or delete settings.

marketing_list_settings

Read-only list of Marketing Studio video modes (formats) and their example presets. Each format has a `slug` (pass as generate_video params.mode) plus example presets carrying ready-to-reuse `params`. Let the user pick a format before generating — or choose the best fit yourself if they asked you to decide. Does not create or modify marketing assets.

marketing_list_video_presets

Read-only list of Marketing Studio webproducts. Does not fetch websites, create webproducts, or modify webproducts.

marketing_list_webproducts