Skip to content
Changelog

Report a bug

Higgsfield integration: operations for AI agents

Higgsfield connects to Type.com as an integration. This page lists the 187 operations documented for Claude and Codex in Type.com: 89 read, 73 write, 25 destructive.

About Higgsfield

Generate AI images, video, audio and 3D with Higgsfield, run presets and ad studios, manage projects, media and characters, and build and publish Higgsfield websites, all through Higgsfield's hosted MCP server.

Categories: AI image & video generation, Marketing

How to connect Higgsfield to Type.com

Connect
Sign in with Higgsfield (OAuth)
Access
Organization connection: one shared account for the workspace.
MCP
This integration is not available through Type’s MCP server. It remains available in Type.

To add the connection, follow the steps in Space connections.

Documented operations

187 operations. Your connection's permissions determine which operations are available.

187 operations listed.

  • Read

    Ads studio card

    What the Ads Studio card shows: brands, one brand, products or one product. Used by the card.

  • Read

    Ads studio get brand

    Read one Ads Studio brand: how far its research got through the five stages (gather, synthesis, enrichment, products, assets) and what is already usable. Use this to answer "is the research done?" - status done means the brand and its products are ready. Call it when the user asks, not on a timer, and never in a loop: research can take several minutes. Follow next_step: a finished research is offered for ads, never generated on its own.

  • Read

    Ads studio get product

    Read one Ads Studio product and open it as a card: whether Ads Studio has finished reading its page (status queued, in_progress, completed or failed, with fail_reason when it failed) and what it knows - name, price, page, description, selling points. Use this to answer "is the product ready?" after ads_studio_add_product, when the user asks - not on a timer and never in a loop.

  • Read

    Ads studio get run

    Read one Ads Studio generation run: its status and every concept in it, with the ad copy. Opens the generation card, which shows the pictures - there is no image link in the result and none to ask for. Call it when the user asks about a run - never on your own initiative and never in a loop. A run can read done while its pictures are still rendering, so check still_rendering before telling the user the ads are ready. A queued run carries its place in line; a canceled run stays canceled and is not a failure. Name a creative by its concept_id. These pictures are not ordinary generations: do not pass Ads Studio ids to show_generation_by_ids or jobs_wait.

  • Read

    Ads studio list brands

    List the brands in this account's Higgsfield Ads Studio, with each one's research status and how many products it has, and open them as a card the user can browse. Call this when the user talks about advertising an existing brand, so later tools get a real brand_id; when the list is already in this conversation, reuse its ids instead of listing again. This is Ads Studio, the ad-creative workspace: it is not the Marketing Studio brand-kit record (marketing_list_brand_kits) and it does not create or design brand assets. Before the first Ads Studio call in a conversation, load the 'ads-studio' workflow with get_workflow_instructions: it carries the frames, objectives and the research-then-offer flow.

  • Read

    Ads studio list products

    List Ads Studio products and open them as a card the user can browse: name, price, page, how many pictures it has, whether the brand page shows it (picked_for_ads) and whether its ad copy is ready. With brand_id: that brand's products. Without it: every product the user has - of any brand or of none - a page at a time. Use product_id in ads_studio_quote and ads_studio_generate: a generation advertises exactly the products named there, whatever picked_for_ads says. texts_ready=false means the copy is still being written and ads made from it come out weaker.

  • Read

    Ads studio list runs

    List recent Ads Studio generation runs, newest first, optionally for one brand. Use it to find a run whose id was lost, or to check what is already in flight before starting another batch.

  • Read

    Ads studio quote

    Get the cost without starting a generation, reserving credits or spending credits. A user request to create ads, including an exact allocation submitted from the Ads Studio app, authorizes this read-only quote: do not ask for separate permission to quote. Takes the same arguments as ads_studio_generate so the quote matches the run. After quoting a requested generation, show the exact allocation and total credits; use ask_user_input (or ask_user_input_v3) only when that exact host tool is available, otherwise ask one concise chat question. Never invent a host tool or generate before explicit approval of this allocation and cost. A price-only request needs only the quote, not a spending-approval question.

  • Read

    Ads studio run progress

    Progress of one Ads Studio generation run. Used by the generation card.

  • Read

    Ai influencer character sheet presets

    App-only: load a page of AI Influencer character sheet presets with preview media and recreate parameters.

  • Read

    Ai influencer get options

    List available AI Influencer character traits for human and animal tiers. Optionally filter by tier; returns option IDs and tier constraints for ai_influencer_prepare. Does not randomize, quote, create or save a character.

  • Read

    Ai influencer get settings

    Read reusable settings from an existing AI Influencer sheet using its job_id. Returns human or animal traits, identity and Style references, body color and saved appearance variants when present. Does not replay the original batch count, quote, save or generate an image. Pass returned params to ai_influencer_prepare with randomize=false to preserve the design.

  • Read

    Ai influencer list presets

    Browse AI Influencer character-sheet presets with previews and reusable settings. Does not generate a sheet. Pass selected preset settings to ai_influencer_prepare with randomize=false.

  • Read

    Ai influencer prepare

    Prepare an AI Influencer character design and quote the total credit cost for batch_size (one to four sheets, default one) without creating a job or spending credits. Accepts human or animal tiers, traits, brief, seed, at most one confirmed identity image in medias and up to three Style references in item_medias. Preserves animal-v3 look and animal trait choices from saved settings; FNF validates variant IDs against the current catalog. Default randomize=true fills unspecified traits using builder shuffle rules; reference identity traits stay unset unless explicitly selected. randomize=false preserves explicit settings and defaults tier to freak (Bold). Returns exact params, credits and free_gens_remaining when known. For generation, pass these params unchanged to ai_influencer_generate; preview-only requests stop here. Repeating preparation may produce a different random design.

  • Read

    Animation actions

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

  • Read

    Apps describe

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

  • Read

    Assets picker list

    List existing uploaded, generated, or liked image/video assets for an app picker. Invoked only by the app; never uploads, generates, or modifies assets. Generations and liked assets support combined image/video kinds and an accessible project or exact folder scope. Sort generations by creation time, project assets by time added, and liked assets by time liked. Uploads also support last-used. Available sorts depend on source and scope.

  • Read

    Balance

    Get the user's available credits and current subscription plan. For transaction history, call `transactions` instead.

  • Read

    Get account overview

    Retrieve the authenticated user's available free-trial offer and account URL for display in the app. Fetching the offer may create a checkout session, but does not start a trial or charge a payment method. Invoked only by the app.

  • Read

    Get explainer presets

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

  • Read

    Get folder

    Read exactly one existing folder_id inside project_id. Does not list children or create a folder.

  • Read

    Get katana config

    Create a run session for a specific published Katana preset. This tool writes session state. Call for every Katana preset run, whether paid or free, after reading all get_preset_instructions parts and collecting required inputs. Reading instructions, browsing presets or asking about free balance alone does not start a run. Set free_generation to false for a paid tracking session, or true only when the user explicitly requests a free run; true spends the backend Katana free run when starting. Bare /katana must first resolve to a specific preset. Reuse the same idempotency_key on retries; never create a session just to reread instructions. Forward the returned preset_session_id in every generation, cost estimate and batch item in this run. Add use_free_gens: true only when the user explicitly requests free generations; a session alone does not select free billing.

  • Read

    Get katana preset submission

    Check whether the authenticated user has submitted an uploaded video as a Katana community preset in their selected workspace. Returns the saved receipt, prompt and reference IDs, or submitted=false when no submission exists. Submission does not imply delivery, approval or public availability. Invoked only by the app.

  • Read

    Get playable game publication

    Read a game's publication in the Higgsfield Supercomputer community: deploy status (pending, live or failed), live URL, deploy error and community listing. Pass playable_id, or the app_id publish_playable_game returned for a file_id game. status not_published means the game has no app yet.

  • Read

    Get preferences

    Read the user's saved MCP project preference before the first generation in a conversation without a destination. auto_create_project defaults to false: omit folder_id and generate without creating a project. When true, create one project on first generation and reuse its destination for this conversation. An explicit existing project or request to work without a project takes priority. A one-off request to create a project is allowed regardless of this flag and does not change it. Never infer another chat's destination. If reading fails, do not auto-create a project.

  • Read

    Get preset instructions

    Resolve a named Higgsfield preset or command and read its instructions without executing it. For every Katana preset run, read all instruction parts and collect required inputs, then call get_katana_config to register the session, whether the run is paid or free. Set free_generation: false for a paid run, or true only when the user explicitly requests a free run. Forward its preset_session_id in every generation, cost estimate and batch item. Add use_free_gens: true only when the user explicitly asks for free generations. Reading instructions, browsing or asking about free balance alone must not create a session. Entries include image/video recipes, explicit-only production commands /ugc-video, /faceless-video and /ad-multiplier (OpenAI), 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. Katana presets resolve by /slug or explicit /katana/slug to the shared Katana workflow with their published reference video and optional CMS creative context, and bare /katana returns general Katana instructions (inspect attachments, edit source media to the user's brief, remix a reference edit, or open the Katana catalog when nothing is supplied); for a /katana/ message with a MEDIA block, pass its entries as media to receive their file URLs. Do the same for a /content-factory message with a MEDIA block. Omit preset to list recipes, commands and published Katana titles/descriptions without opening a widget. To choose a Katana preset by style or theme, match this metadata and then load its exact /katana/slug; do not use get_presets for internal Katana discovery. 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. Unknown emoji commands return mode instructions with recipe choices: preserve supplied media and ask the user to choose before generation; never truncate a mixed command, guess an effect or use ordinary-generation fallback. Other unqualified unknown tokens return mode instructions with instructions_markdown in structuredContent: infer the task and use ordinary generation tools instead of searching the gallery or stopping at an offer. An unavailable /katana/slug must stop without substituting another preset.

  • Read

    Get presets

    Search and browse reusable image and video generation presets from Higgsfield's Viral, Marketing Studio, Genjutsu, Katana, Soul and personal Recraft style galleries, or retrieve a preset's inputs and preview without starting a generation. For sources other than Katana, Soul and Recraft: 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. For sources other than Katana and Recraft, pass query to search preset names, descriptions and types before pagination. All query words must match; omit source to search Viral and Marketing Studio. Pass preset_id to open a published preset detail preview directly. Omit source to browse Viral and Marketing Studio; limit applies to the complete page. source='genjutsu' lists Genjutsu motion presets, with category='genjutsu', 'genjutsu-trending' or 'genjutsu-new'; a bare /genjutsu opens this gallery. To choose motion for an existing AI Influencer, pass initial_inputs:{character_sheet:[{id:"<confirmed sheet job UUID>",type:"image_job"}]} — character_sheet must be a one-item array, not a single object; legacy source='marketing_studio' still accepts these categories and genjutsu: IDs. category='genjutsu-styles' lists Genjutsu Styles: named looks (e.g. Knitted Yarn World, Rounded Toy CGI) that redraw the user's own video while keeping its motion. When the user names a look, search it with query; preset_id 'genjutsu-style:<id>' opens its form, and initial_inputs {video:[<confirmed video UUID>], references?, resolution} adds readiness and price. source='soul' browses curated Soul 2.0 image styles. Search with query or open a style with preset_id and source='soul'. Each item's id is the style_id for generate_image or generate_image_batch with model='soul_2'; do not call execute_preset for Soul styles. A style can be combined with soul_id, but not with medias/image references. Preview images are catalog samples, not generation inputs. Browsing or selecting a style does not authorize generation. source='recraft' browses the caller's own completed Recraft styles saved in Higgsfield, not general presets or styles in a separate Recraft account. Search names by substring with query or open a style with its UUID as preset_id. Each item's id is the style_id for generate_image or generate_image_batch with model='recraft_v4_styles', not recraft_v4_1. Do not call execute_preset for these styles. Preview images are samples, not generation inputs. Browsing or selecting a style does not authorize generation. An empty catalog means no matching ready personal styles are available; do not substitute a general style. 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'. source='katana' is a user-facing catalog, not headless search: query and initial_inputs are unsupported. preset_id:'<slug>' opens one Katana preset's input form directly; use it only as the loaded /katana/slug instructions direct, when the user asked to run that preset and its inputs are missing. To find or choose a Katana preset for a task, call get_preset_instructions with preset omitted, match the returned titles/descriptions, then load its exact /katana/slug. Do not open this gallery merely to choose a preset for supplied media. Explicit catalog browsing opens the Katana catalog without default filters; category supports personalized_edits, style_transfer and motion_transfer, katana_source supports community or higgsfield. Katana uses opaque string cursors and backend-default page sizes (explicit limit maximum 20). Recreate selections resolve exact /katana/slug instructions with get_preset_instructions. Katana browsing does not execute a preset. source='what_if' opens the What If style gallery of /content-factory, where the user picks a style and types the prompt; call it only for a bare /content-factory or when the user asks to browse What If styles, never when a topic is given. It takes no other filters and does not start a generation. Use category slugs returned by this tool and pass next_cursor only when the user asks for another page.

  • Read

    Get project

    Read metadata and current capabilities for one existing project root by ID. Returns only shared project metadata and access capabilities; it does not expose Supercomputer instructions, knowledge sources, connectors, or skills. Requires the project_id and an explicit workspace_id request context. Does not change workspace selection or chat destination.

  • Read

    Get project asset prompt

    Read only the prompt details for one accessible placement_id in this project. Does not list other assets or read source download metadata.

  • Read

    Get project asset source

    Read only source details for one accessible placement_id in this project. For confirmed files includes download URL and file metadata. Does not generate or upload media or return prompt details.

  • Read

    Get project publication

    Read current Cinema publication settings, effective prompts/canvas/discovery visibility, snapshot and moderation state without changing anything. Show the user current settings, content exposure and flagged items before seeking host approval for a separate mutation. Backend visibility defaults are true; discovery disabled leaves a public link public. After an uncertain write this observes current state only, not a per-operation receipt. The private working-project name, public publication title (settings.name), and URL slug (settings.slug) are distinct; never infer a title or slug change from a working-project rename. For a share-link request, preserve any existing slug; prepare a nonempty URL-safe slug in the proposal only when absent or when the user requests a URL change, before approval and verify public_url after completion. show_canvas does not establish whether chats are hidden; no separate chat-privacy control or complete composition inventory is available, so do not promise that chats are excluded. Pending moderation runs automatically: wait and read state; only awaiting_confirm needs a separate flagged-item decision. Capture can include changes made while publication is in flight; after a completed snapshot, later working-project changes require republishing. Report completion only from observed state and review, never merely an accepted mutation response. For republish, compare snapshot_id and processing state with the prior observation. An unchanged snapshot may be a successful no-op when current content is already served, or the old version while work is in flight; do not infer pending from an unchanged ID. Report observed state and any attribution uncertainty; neither a new snapshot nor current state is a per-call receipt.

  • Read

    Get workflow bundle file

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

  • Read

    Get workflow instructions

    For an explicit named preset slash command, resolve get_preset_instructions first and follow its recipe instead of selecting a workflow by name similarity. Katana: general /katana loads workflow 'katana' to inspect supplied attachments, edit source footage according to the user's brief, or produce a finished reference-based video remix with new scenes, motion and text. A source edit does not require a separate reference or a preset; attachments alone authorize inspection, not paid generation. Discover a suitable reference when a substantive creative brief supplies no reference or source footage; never substitute for a specifically requested but unavailable reference. Analysis alone, a standalone subject swap, restyle or motion-transfer job, ad variants, and adaptation only of an ad's persuasive structure do not activate Katana. Ad 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, regenerate the same ad with different people or products, or recreate one supplied ad as new footage for another market, audience, spoken language, cast, or product. Load this workflow before Marketing Studio, model browsing, or direct generation. For finished-file cuts, clip assembly, soundtrack changes or burned speech captions, load video-montage. For native Higgsedit project and motion-graphics authoring use video-editing. UGC production uses the single ugc-video workflow and its selected format. 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, Higgsfield Ads Studio — ad creatives, including Meta / Facebook / Instagram ads, for a product or a brand, with or without a brand: from a brand's website, an existing Ads Studio brand or product, a product page link, a product photo with a description, or a prompt alone, and anything about an existing Ads Studio brand, product or generation run ('ads-studio'): load it before the first ads_studio_* call, and before any image tool when the user asks for ads, 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.

  • Read

    Job display

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

  • Read

    Job status

    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.

  • Read

    Jobs wait

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

  • Read

    Katana compose message

    Validate a filled Katana preset form and return the chat message that starts the preset.

  • Read

    List folders

    List direct child folders of parent_folder_id, defaulting to the project root. Optional search filters only these child names. Use get_folder for one ID or search_folders for project-wide name search. Returns actual project workspace even for empty pages. Continue cursor with the same workspace, project, parent and search; an empty page with has_more=true is not completion.

  • Read

    List project assets

    List metadata for generations and uploaded media/files placed in this project. Omit folder_id for all accessible ordinary folders; supply it for exactly one folder without descendants. placement_id is the placement; item_id is its job or upload. No prompts, URLs or previews are returned. For jobs use item_id with job_status/job_display and the item's folder_id as context. Continue cursor with the same workspace, project and filters; empty items with has_more=true is not completion.

  • Read

    List projects

    List or find existing accessible Higgsfield media projects before choosing a generation destination. Returns project_id, default_folder_id and each project's actual workspace_id. Includes accessible shared projects across workspaces; workspace_id sets authenticated request context, not a filter. Does not list websites, 3D scenes or local directories and never creates a project. Read one page at a time; pass cursor with the same workspace and search to continue. An empty page with has_more=true is not the end.

  • Read

    List voices

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

  • Read

    List website categories

    List 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).

  • Read

    List websites

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

  • Read

    List workspaces

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

  • Read

    Marketing list avatars

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

  • Read

    Marketing studio v2 avatars

    Widget-internal: list the user's Marketing Studio avatars (preset and custom) for the avatar picker.

  • Read

    Marketing studio v2 costs

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

  • Read

    Marketing studio v2 presets

    Widget-internal: load a page of the Marketing Studio v2 preset feed for a category.

  • Read

    Marketing studio v2 status

    Widget-internal: poll status and results of submitted Marketing Studio v2 jobs.

  • Read

    Models explore

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

  • Read

    Prepare generation

    Read a source generation's original model and complete parameters for the app's Recreate context. Prepares settings for the next user request; does not submit or generate anything.

  • Read

    Resolve project assets

    Locate existing project placements for typed sources [{type,id}]. Source ID means the original job/upload ID, not placement_id. Optionally limit to one exact folder. Continue cursor with the same workspace, project, folder and sources; empty items with has_more=true is not completion.

  • Read

    Scene builder 3d get artifact

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

  • Read

    Scene builder 3d get blend

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

  • Read

    Scene builder 3d get collaboration

    Read the 3D Jutsu editor snapshot, entity versions, World settings and journal after an optional sequence. Widget-only companion to scene_builder_3d_get_project; download the checkpoint with scene_builder_3d_get_glb.

  • Read

    Scene builder 3d get generation

    Read a generation launched by scene_builder_3d_generate_angles or scene_builder_3d_generate_video. Poll while submitting/running. succeeded and failed are final; submission_unknown requires reconciliation, never an automatic new paid generation. Results contain FNF job IDs and image/video URLs. Do not claim success before succeeded or claim visual quality without inspecting the image.

  • Read

    Scene builder 3d get glb

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

  • Read

    Scene builder 3d get operation

    Read 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. OPERATION_NOT_FOUND is terminal for polling: stop, verify the IDs and submission result, and read the project. Never poll an operation rejected with REVISION_CONFLICT. 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 scene inspection/edit call of that review phase, 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. Show an unchanged revision only once. Authorized generation and status calls may follow; later feedback or a verified mismatch can reopen scene editing. Verify and show the corrected revision at its next review boundary. This shows the result to the user; a text summary or download link alone does not finish scene delivery.

  • Read

    Scene builder 3d get project

    Read 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. Before building or editing a scene, load get_preset_instructions with { preset: "/3d-jutsu" } once for the full workflow, runtime limits and scene-building references.

  • Read

    Scene builder 3d get scene asset

    Resolve a signed GET for a scene asset referenced by an object.create.from_glb journal operation from scene_builder_3d_get_collaboration. Widget-only; use the asset ID, not a catalog ID or URL.

  • Read

    Scene builder 3d list generations

    Read the shared image/video generation history of a 3D Jutsu project, newest accepted first. Includes pending and failed attempts. Pass nextCursor as before for older records; status changes never reorder records. Use scene_builder_3d_get_generation for an individual result.

  • Read

    Scene builder 3d list projects

    Discover 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. Before building or editing a scene, load get_preset_instructions with { preset: "/3d-jutsu" } once for the full workflow, runtime limits and scene-building references.

  • Read

    Scene builder 3d query python

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

  • Read

    Scene builder 3d search assets

    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.

  • Read

    Scene builder 3d show scene

    Show an interactive 3D scene preview of an existing 3D Jutsu project. 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 at the scene review boundary after settlement and verification. Do not repeat an unchanged revision. Authorized generation/status calls may follow; feedback or a verified mismatch can reopen editing and lead to a newly verified revision. 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.

  • Read

    Search folders

    Find folder names across the whole project using a nonempty search. Use list_folders for direct children. Continue cursor with the same workspace, project and search; inspect has_more even when items is empty.

  • Read

    Shorts studio list presets

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

  • Read

    Shorts studio list sessions

    List the caller's past Shorts Studio sessions (newest first) to find a session_id to poll with shorts_studio_status.

  • Read

    Shorts studio status

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

  • Read

    Show generation by ids

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

  • Read

    Show generations

    Browse completed non-Marketing Studio generation history by default, or include all job states for a live feed with only_completed=false. Renders 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.

  • Read

    Show marketing studio generations

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

  • Read

    Show marketing studio v2

    Open 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 in UGC, ads, posters or marketplace categories. For product-shot or motion catalog browsing, and /marketing-studio, use get_presets instead. 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.

  • Read

    Show medias

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

  • Read

    Tiktok accounts

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

  • Read

    Tiktok music tune

    Open 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. This editor previews settings only; they are not applied to the post. For publication, ask the user to select and tune music in the publish-form widget opened by tiktok_prepare_publish. Read-only.

  • Read

    Tiktok publish status

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

  • Read

    Transactions

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

  • Read

    Video analysis jobs

    List the user's video analyses in the current workspace, newest first. Paginate by passing the previous response's cursor.

  • Read

    Video analysis status

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

  • Read

    Visual effects history

    Read one page of the user's accessible Viral preset generations. Does not generate media.

  • Read

    Visual effects list

    Read the website's public visual preset previews and category filters. Does not generate media.

  • Read

    Visual effects samples

    Read approved public examples and their input media for a visual preset. Does not generate media.

  • Read

    Website db

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

  • Read

    Website secrets

    List configured secret names only. Values are never returned. Configure or remove secret values through Higgsfield's website settings; do not ask the user to paste credentials into chat. Secret changes take effect on the next deploy_website.

  • Read

    Website status

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

  • Read

    What if compose message

    Validate a filled What If form and return the /content-factory chat message that starts the short.

  • Write

    Ads studio create brand

    Research a brand from its website and build its Ads Studio brand profile: products, palette, logo, tone and audience, read from the live site. Pass the website when you have it - with a URL the research starts at once and takes a few minutes; with only a name Ads Studio answers with the site it thinks was meant and starts nothing, so confirm that with the user and call again with the URL. This reads the brand's own public website. It does not design logos or brand assets (that is the brand-asset-creation workflow) and it is not the Marketing Studio brand-kit record (marketing_create_brand_kit). Before the first Ads Studio call in a conversation, load the 'ads-studio' workflow with get_workflow_instructions.

  • Write

    Ads studio generate

    Generate ad creatives in Ads Studio: for a brand, for products of any brand or of none, or from a prompt and the user's pictures alone, with or without the brand kit. Ads Studio writes the concepts and renders the pictures. This spends Higgsfield credits, so quote with ads_studio_quote and get explicit approval of the exact allocation and credit cost first. An approval from the Ads Studio app allocation is NOT approval. When allocation is supplied, this tool quotes the whole allocation and requests native MCP form confirmation when supported. Otherwise it returns approval_required and credits: show the exact counts and cost, ask for explicit chat approval and stop. Only after approval, repeat the unchanged allocation with expected_credits. Never split the allocation or bypass a supported native form. Answers as soon as the runs are accepted, with a run id each - report those and stop; read ads_studio_get_run when the user asks, never in a loop. Generation takes a few minutes.

  • Write

    Ai influencer generate

    Generate and save one to four AI Influencer character sheets in the selected Higgsfield workspace from exact params returned by ai_influencer_prepare. Does not train a Soul or generate video. Rechecks price before submission and rejects paid prices above max_credits. Paid generation spends existing credits; it does not purchase credits or subscriptions. use_free_gens=true requires explicit user intent and backend eligibility, with max_credits=0 for free-only requests; never falls back to paid generation. Returns job_id for the first accepted job and job_ids for a batch before completion; wait for every returned job. Free generations always submit one sheet. Repeating this call can create another job and spend credits again; never automatically retry an uncertain submission. An auto-updating generation widget shows every accepted sheet and its progress. Wait with jobs_wait (timeout_seconds <= 15); do not call show_generation_by_ids or job_display again unless the user requests a separate display. After completion, offer Genjutsu animation and wait for agreement before opening motion presets.

  • Write

    Apps invoke

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

  • Write

    Attach project asset

    Attach an existing accessible typed source ID to folder_id. Upload and confirm a new file using media_upload/media_confirm with source_type=file_input first. Reattaching the same source to the same folder reuses its placement. Inspect assets after an uncertain receipt; never blindly repeat mutations.

  • Write

    Build ai influencer

    Create one to four AI Influencer character sheets in chat using the builder backend, without training a Soul. Not for text-only concepts or opening the builder UI. options lists traits; presets browses character presets; recreate loads a sheet job's settings without generating. quote accepts tier, selection, brief, seed, batch_size (one to four), up to one confirmed identity reference in medias and up to three Style references in item_medias. Animal v3 look and trait choices from saved settings are preserved. Default randomize=true fills unspecified traits using the UI shuffle rules; randomize=false keeps only explicit choices and defaults tier to freak (Bold). With a reference, identity groups stay unset unless explicitly chosen. To reuse preset/recreate params, spread them into quote with randomize=false. Quote returns exact params, credits and free_gens_remaining when known. Report design and price, respect preview-only requests and budgets. Only submit starts a generation job and saves its character sheet in the selected Higgsfield workspace. Paid submit spends existing Higgsfield credits; it does not buy credits or start a subscription. It returns job_id for the first accepted job and job_ids for a batch before generation completes; track every returned job. Free generations always submit one sheet. Repeating submit can create another job and spend credits again. submit sends quoted params unchanged with max_credits; a fresh quote checks the cap before submission. use_free_gens=true requires explicit user intent and backend eligibility; it spends no credits and must never fall back to paid generation. Use max_credits=0 for free-only requests. Never retry uncertain submissions automatically. Wait with jobs_wait, then show_generation_by_ids. After displaying a completed sheet, offer to animate it with Genjutsu unless the user declined animation suggestions. Wait for agreement unless animation was already requested; with multiple sheets, first ask which character. Then open get_presets source genjutsu category genjutsu with initial_inputs.character_sheet containing that exact completed image_job. Let the user choose motion and review settings and price before generating video; never submit video automatically. Does not generate video.

  • Write

    Copy project asset

    Copy source_placement_id into target_folder_id, optionally in target_project_id. Omit target_project_id for this project. Creates another placement, not a new uploaded source. Creation is not idempotent: do not repeat an uncertain copy automatically.

  • Write

    Create folder

    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.

  • Write

    Create project

    Create a private Higgsfield media project for this conversation. Create only on an explicit user request or when get_preferences returns auto_create_project=true and this conversation has no destination. The default is no automatic project. An explicit existing destination or request to work without a project wins. Creating a project does not change the saved preference. Call once, 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.

  • Write

    Create voice

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

  • Write

    Create voice from confirmed audio

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

  • Write

    Create website

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

  • Write

    Dubbing

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

  • Write

    Execute preset

    Request execution of one published preset from the Viral, Marketing Studio or Genjutsu gallery, including a Genjutsu Style (genjutsu-style: preset_id) that restyles the user's own video. 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.

  • Write

    Generate 3d

    Generate a 3D GLB mesh. Use `models_explore(type:'3d')` to pick a model and see its `medias[].roles` and `parameters`. Attached/local file: upload it yourself if readable (`media_upload`, curl PUT, `media_confirm`), else 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 the completed model's public HTTPS GLB URL, not a job ID; for a GLB made in the sandbox, upload it with `media_upload` (a .glb filename), curl PUT and `media_confirm` type file, then pass the `url` media_upload returned, never its `upload_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. Put all generation arguments inside `params`, with model-specific fields beside `model`. Apply `adjustments` returned by the server. If `recovery_tool` is returned, call it immediately. `get_cost:true` preflights credits without submitting. 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.

  • Write

    Generate audio

    Generate one music or speech/voice request 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 speech 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. When the catalog exposes suno_music or suno_mashup, use them for music with required integer duration (15-360 seconds). For suno_music, prompt supplies description in simple mode; explicit description, lyrics, or style take precedence and prompt remains a display label. Do not combine description with lyrics/style. For instrumental style mode, pass instrumental:true and style. For suno_mashup, pass exactly two audio references using the catalog media roles; prompt is a display label only, and style requires lyrics. 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. Submitted audio requests can send text and reference inputs to external audio model providers through Higgsfield and consume credits. 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.

  • Write

    Generate audio batch

    Submit 1-12 independent audio generations in parallel without opening a widget. Requests can send text and reference inputs to external audio model providers through Higgsfield and consume credits. 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 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. 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.

  • Write

    Generate image

    Generate 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. Attached/local media: if your code environment can read the file, upload it yourself (`media_upload`, curl PUT, `media_confirm`); otherwise 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_5` — 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. 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.

  • Write

    Generate image batch

    Submit 1-12 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 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. 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.

  • Write

    Generate video

    Generate 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, upload readable files yourself first (`media_upload`, curl PUT, `media_confirm`); only if unreadable or the PUT fails, call `media_upload_widget` as the only tool in that turn. Never 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, `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. 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.

  • Write

    Generate video batch

    Submit 1-12 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 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. 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.

  • Write

    Manage reference elements

    Elements 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. REUSABLE CHARACTER — user wants a recurring character/face across generations: create an Element (this tool action=create) from one clear reference image. USAGE IN GENERATION (implementation detail): 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 names to model ids. Other models ignore the placeholder. USER-FACING STYLE: prefer friendly model names and element names for readability. 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`.

  • Write

    Marketing studio v2 create

    Widget-internal: recreate a Marketing Studio v2 preset — validates inputs against the preset's recreate contract and submits one generation.

  • Write

    Media confirm

    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.

  • Write

    Media import url

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

  • Write

    Media upload

    Upload 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[]. Default path for user-attached image/video/audio whose bytes your code environment can read (e.g. /mnt/user-data/uploads in Claude): call this, PUT the file to upload_url with curl, then media_confirm — do not ask the user to re-upload. Fall back to media_upload_widget only when the file is unreadable or the PUT fails.

  • Write

    Media upload widget

    Fallback local-media intake for Higgsfield in Apps UI-capable clients. When the user refers to an attached/local photo, image, video, or audio with no confirmed media_id, first upload it yourself if your code environment can read the file (e.g. /mnt/user-data/uploads): media_upload, curl PUT, media_confirm. Call this widget as the only tool in the turn only when the file is unreadable there or the PUT fails. Do not 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.

  • Write

    Motion control

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

  • Write

    Move folder

    Move one folder under target_parent_id inside the same project. Backend checks membership and cycles. Inspect the folder after an uncertain outcome before retrying.

  • Write

    Move project asset

    Move an existing placement_id to target_folder_id, optionally in target_project_id. Does not duplicate the source. Inspect assets after an uncertain receipt before retrying.

  • Write

    Outpaint image

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

  • Write

    Project camera media

    Save a confirmed camera recording or shot to its project, or resolve an accessible uploaded draft for playback. Does not generate media.

  • Write

    Project metadata

    App-only project header. Read an accessible project's name and rename capability, or explicitly rename that same project. Changes only its name; no scene edits or media generation.

  • Write

    Publish katana preset

    Submit an uploaded video as a Katana community preset for the authenticated user in their selected workspace, optionally including the original prompt and up to ten uploaded image or video references. Returns a submission receipt; acceptance does not mean the preset is publicly available. Invoked only by the app. Identical submissions reuse their receipt; changed details for an already submitted video are rejected.

  • Write

    Publish website

    Publish 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).

  • Write

    Reframe

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

  • Write

    Register katana result

    Save one verified final video from a named Katana preset as a completed job in the selected workspace. Pass preset_id and the confirmed final video media_id, the run preset_session_id from get_katana_config, and optionally folder_id. The final job set is added to that session, including when the session is already closed. This links the existing video without copying files, generating, charging generation credits or publishing to the community. Keep media_upload → PUT → media_confirm for local/sandbox exports; if the final video is already confirmed, reuse its media_id. Never pass URLs, local paths, job IDs, drafts, references or comparison videos. On timeout repeat the same inputs and media_id; one video can register one result. Do not regenerate or reupload to retry. A completed response contains job_id for show_generation_by_ids.

  • Write

    Register what if result

    Save one verified final /content-factory what-if short as a completed job in the selected workspace. Pass the confirmed final video media_id, the What If style preset_id when one was used, the episode number when the turn makes several, and optionally folder_id. This links the existing video without copying files, generating or charging credits. Call it once per final video, after media_confirm. Never pass URLs, local paths, job IDs, drafts or reference videos. On timeout repeat the same inputs; one video can register one result. Do not re-render or reupload to retry.

  • Write

    Rename folder

    Rename one folder inside this project. Does not move or delete its contents.

  • Write

    Reset balance

    INTERNAL — claim the displayed reset ONLY after the user clicks Reset balance in the widget. Pass the exact scope and workspace_id from that offer. Never call this tool from the assistant or automatically retry a claim. After a conflict or uncertain result, refresh availability through the widget before another explicit claim.

  • Write

    Resolve explainer preset

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

  • Write

    Reveal generation

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

  • Write

    Scene builder 3d create project

    Create 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. Before building or editing a scene, load get_preset_instructions with { preset: "/3d-jutsu" } once for the full workflow, runtime limits and scene-building references.

  • Write

    Scene builder 3d generate angles

    Generate an AI image from a rendered 3D Jutsu scene using 3d_jutsu_angles (Seedream V5 Pro pricing). This spends credits. First render and inspect an image with scene_builder_3d_query_python and scene_builder_3d_get_artifact. Supply that operationId/artifactId; optionally include referenceMediaId for an accessible uploaded photo or uploaded first video frame alongside the scene render. The Runner records the immutable references and shared project history. The scene itself is unchanged. After submission, use scene_builder_3d_get_generation. If the response is lost, look up generationId=requestId or repeat exactly the same requestId and arguments, including the reference; never allocate a fresh ID just to retry. Use a new UUID only for an intentional additional generation.

  • Write

    Scene builder 3d generate video

    Generate a paid Seedance 2.5 video in a 3D Jutsu project. Use a prompt alone (t2v), medias with image/start_image/end_image/video/audio roles (omni_reference), one video for video_edit, or videos plus extensionMode for video_extension. References use data:{id,type} from accessible FNF uploads or prior jobs, never URLs. Supports up to 30 images, 10 videos, 10 audio clips, 50 total. Optionally supply operationId/artifactId together to use a published Blender render as start_image; it counts toward the limits and cannot coexist with another start_image or non-omni mode. Omit mode to infer t2v or omni_reference. Supports bitrateMode, draft (480p) and draftJobId (1080p finalization, mutually exclusive with draft). Worker saves all inputs and shared project history. Preserve requestId and identical arguments on retry; poll scene_builder_3d_get_generation. Never allocate a new ID to recover an uncertain submission.

  • Write

    Scene builder 3d import asset

    Import 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 scene inspection/edit call of that review phase, 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. Show an unchanged revision only once. Authorized generation and status calls may follow; later feedback or a verified mismatch can reopen scene editing. Verify and show the corrected revision at its next review boundary. This shows the result to the user; a text summary or download link alone does not finish scene delivery.

  • Write

    Scene builder 3d phone camera

    App-only phone pairing for the 3D Angles recorder after scene_builder_3d_get_project. Create a room, renew its host ticket, or stop it. Does not modify project cameras or generate media.

  • Write

    Scene builder 3d upload catalog asset

    Upload a confirmed catalog GLB into the authorized project's current settled revision. Widget-only. sha256 must match the bytes displayed by the editor. Returns only the uploaded scene asset ID, which the editor references in one object.create.from_glb operation through scene_builder_3d_apply_scene_operations. This does not create a scene object.

  • Write

    Select workspace

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

  • Write

    Set generation like

    Like or unlike a generation for the authenticated user from the app. Sets the requested state; repeated requests are safe. Pass folder_id when acting from a project so its LIKE permission is checked; unlike removes only the user's own bookmark even after access is revoked.

  • Write

    Shorts studio create

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

  • Write

    Shorts studio create preset

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

  • Write

    Show characters

    Soul 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`.

  • Write

    Show credit reset

    Open the Credit Reset widget when the user invokes /reset-credits or asks to see their reset offer. Opening it never claims credits or changes the subscription. Use the returned scenario and phase. Errors mean availability could not be checked, not account ineligibility. Never invent an offer, amount or successful claim.

  • Write

    Show katana result

    Display the final completed Katana video in its result widget with preview and download. Retained for backward compatibility; prefer show_result with action for new calls. Call after verifying the final export. Pass exactly one of media_id (a confirmed owned video UUID) or url (a public HTTPS video URL, up to 50 MB). URL input imports and confirms the video in your media library before displaying it. Prefer media_id for an already uploaded video to avoid duplicate uploads. Never pass a job ID, local path or unfinished render.

  • Write

    Show plans and credits

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

  • Write

    Show reference elements

    Elements 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. REUSABLE CHARACTER — user wants a recurring character/face across generations: create an Element (this tool action=create) from one clear reference image. USAGE IN GENERATION (implementation detail): 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 names to model ids. Other models ignore the placeholder. USER-FACING STYLE: prefer friendly model names and element names for readability. 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`.

  • Write

    Show result

    Display a final completed video in its result widget with preview and download. For an active Katana free-generation session, include preset_session_id with action "katana_video"; the session closes after video validation and before returning the result. Call after verifying the final export. Include a nonempty action string, the preset command when a preset run produced the video, optionally include meta as any JSON object, and pass exactly one of media_id (a confirmed owned video UUID) or url (a public HTTPS video URL, up to 50 MB). URL input imports and confirms the video in your media library before displaying it. Prefer media_id for an already uploaded video to avoid duplicate uploads. Never pass a job ID, local path or unfinished render.

  • Write

    Sync agents

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

  • Write

    Tiktok connect

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

  • Write

    Tiktok prepare publish

    Step 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). The user reviews and submits the publish-form widget, including optional music selection and tuning. Do not call tiktok_publish yourself. Clients without MCP Apps cannot 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.

  • Write

    Tiktok publish

    Publish a prepared TikTok post from the publish-form widget after the user reviews and submits it. Requires the short-lived publish_token delivered only in tiktok_prepare_publish result metadata. Chat confirmations and boolean attestations do not authorize publication. Use tiktok_prepare_publish to open the form; clients without MCP Apps cannot publish. Track a submitted post with 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.

  • Write

    Tiktok reconnect

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

  • Write

    Track generation download

    Record a generation download started by the authenticated user in the app.

  • Write

    Unarchive project

    Restore one archived project. Does not create a new project or modify its contents.

  • Write

    Update preferences

    Persist whether to automatically create a media project for new MCP conversations. Call only when the user asks to enable or disable this saved preference (for example, always create a project for new chats). A one-off create-project or no-project request must not change this preference. Does not create, delete or move any projects or existing media. Other preferences remain unchanged.

  • Write

    Upscale image

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

  • Write

    Upscale video

    Upscale 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).

  • Write

    Use higgsfield

    Interact with Higgsfield through a single interface for app services and UI actions. Use action to select the operation and page to identify the current app page. If action is omitted, the app is initialized; if page is omitted, home is used. Returns structured data for the requested operation.

  • Write

    Video analysis create

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

  • Write

    Virality predictor

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

  • Write

    Voice change

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

  • Write

    Website repo access

    Prepare a credential-free checkout in sandbox_exec (operation checkout), or push committed changes (operation push). Use the returned checkout_path to edit and commit with sandbox_exec; then call this tool with push before deploy_website. Each call reserves the user's sandbox for 15 minutes. Checkout reuses existing files; it never resets work. Push rejects uncommitted files and non-fast-forward updates. No Git credentials are returned or installed in the editing sandbox.

  • Destructive

    Ads studio add product

    Add a product to Ads Studio - under a brand, or with no brand at all - from its page link and/or a pasted description. Answers as soon as the row is queued - Ads Studio reads the page in the background. Do not poll and do not list products to check. Read ads_studio_get_product when the user asks about it. Use this when the research missed a product or the user names a new one. To refresh an existing product from its page, pass its id in overwrite instead of adding a second row.

  • Destructive

    Ads studio cancel run

    Cancel a queued or running Ads Studio generation. Pictures already rendered stay; a run too far along to stop answers that it can no longer be canceled. Only cancel when the user asks.

  • Destructive

    Ads studio update product

    Change one Ads Studio product, or hide it from the brand page. picked_for_ads=false hides it and true shows it again; neither deletes anything, and a generation still advertises exactly the products it names. Every other field is a merge patch: what you leave out is left alone. Use the user's own words for the copy fields; do not invent selling points they did not say.

  • Destructive

    Archive project

    Archive one project reversibly. Inspect get_project capabilities first when permissions are unclear. Restore it with unarchive_project.

  • Destructive

    Cancel project publication review

    Cancel the CURRENT open publication review after explicit user approval. No review-ID binding exists. Cancellation does not roll back metadata already saved by preview/update/publish, and does not unpublish an existing publication. Obtain explicit user approval through the MCP host before invoking this tool. The host owns its approval policy; the server cannot independently verify a human decision. Do not invoke based only on inferred intent. After an uncertain response, stop and read get_project_publication to observe current state. There is no per-operation receipt or automatic replay guarantee; do not blindly repeat a publication mutation. The private working-project name, public publication title (settings.name), and URL slug (settings.slug) are distinct; never infer a title or slug change from a working-project rename. For a share-link request, preserve any existing slug; prepare a nonempty URL-safe slug in the proposal only when absent or when the user requests a URL change, before approval and verify public_url after completion. show_canvas does not establish whether chats are hidden; no separate chat-privacy control or complete composition inventory is available, so do not promise that chats are excluded. Pending moderation runs automatically: wait and read state; only awaiting_confirm needs a separate flagged-item decision. Capture can include changes made while publication is in flight; after a completed snapshot, later working-project changes require republishing. Report completion only from observed state and review, never merely an accepted mutation response. For republish, compare snapshot_id and processing state with the prior observation. An unchanged snapshot may be a successful no-op when current content is already served, or the old version while work is in flight; do not infer pending from an unchanged ID. Report observed state and any attribution uncertainty; neither a new snapshot nor current state is a per-call receipt.

  • Destructive

    Cancel trial auto renewal

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

  • Destructive

    Confirm billing purchase

    INTERNAL — 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.

  • Destructive

    Confirm project publication review

    Separately approve publishing with flagged media HIDDEN for the CURRENT awaiting-confirm review. First show the complete current flagged list and visibility and obtain a NEW explicit user decision to proceed with those items hidden. Never automatically invoke after publish/update/preview. No exact review-ID or frozen snapshot binding exists; incomplete lists require Higgsfield web. Obtain explicit user approval through the MCP host before invoking this tool. The host owns its approval policy; the server cannot independently verify a human decision. Do not invoke based only on inferred intent. After an uncertain response, stop and read get_project_publication to observe current state. There is no per-operation receipt or automatic replay guarantee; do not blindly repeat a publication mutation. The private working-project name, public publication title (settings.name), and URL slug (settings.slug) are distinct; never infer a title or slug change from a working-project rename. For a share-link request, preserve any existing slug; prepare a nonempty URL-safe slug in the proposal only when absent or when the user requests a URL change, before approval and verify public_url after completion. show_canvas does not establish whether chats are hidden; no separate chat-privacy control or complete composition inventory is available, so do not promise that chats are excluded. Pending moderation runs automatically: wait and read state; only awaiting_confirm needs a separate flagged-item decision. Capture can include changes made while publication is in flight; after a completed snapshot, later working-project changes require republishing. Report completion only from observed state and review, never merely an accepted mutation response. For republish, compare snapshot_id and processing state with the prior observation. An unchanged snapshot may be a successful no-op when current content is already served, or the old version while work is in flight; do not infer pending from an unchanged ID. Report observed state and any attribution uncertainty; neither a new snapshot nor current state is a per-call receipt.

  • Destructive

    Confirm trial cancel

    INTERNAL — 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.

  • Destructive

    Delete folder

    Delete one folder with explicit confirm_delete=true. cascade defaults to false; folders with children may be rejected. Deleting placements does not physically delete their uploaded sources. Do not retry uncertain outcomes automatically.

  • Destructive

    Delete project

    Permanently delete one project and cascade through its contents. Requires explicit user authorization and confirm_delete=true. Do not automatically retry an uncertain outcome; inspect the project first. Underlying uploaded sources are not promised to be physically purged.

  • Destructive

    Deploy website

    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.

  • Destructive

    Participate in contest

    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.

  • Destructive

    Publish playable game

    Publish a game to the Higgsfield Supercomputer community, where other users can play it; only when the user asks to publish or share it there. Pass playable_id for a Playable Ads game, or file_id with name and cover_url (its poster; icon_url too when there is an icon) for a game built in this conversation (one self-contained .html uploaded with media_upload and media_confirm). This writes the game's current version, title and description into its own Supercomputer app and starts a deploy that takes minutes; the result is status pending with app_id. Check get_playable_game_publication about once a minute; once live, call publish_website with website_id = app_id to list the game or refresh its listing. Call this again to ship a newer version or to retry a failed deploy; while a deploy is pending it changes nothing. A newer version of a file_id game is a new upload with its own app.

  • Destructive

    Publish project

    Save supplied Cinema metadata and request publication through the existing writer, which may capture current working content asynchronously. Before invocation obtain explicit user publication consent AND confirmation of content rights/permission. Disclose current content exposure and the three explicit visibility settings; discovery disabled leaves a public link public. This is not bound to a prior preview. A flagged review requires a separate user decision; never automatically confirm. Obtain explicit user approval through the MCP host before invoking this tool. The host owns its approval policy; the server cannot independently verify a human decision. Do not invoke based only on inferred intent. After an uncertain response, stop and read get_project_publication to observe current state. There is no per-operation receipt or automatic replay guarantee; do not blindly repeat a publication mutation. The private working-project name, public publication title (settings.name), and URL slug (settings.slug) are distinct; never infer a title or slug change from a working-project rename. For a share-link request, preserve any existing slug; prepare a nonempty URL-safe slug in the proposal only when absent or when the user requests a URL change, before approval and verify public_url after completion. show_canvas does not establish whether chats are hidden; no separate chat-privacy control or complete composition inventory is available, so do not promise that chats are excluded. Pending moderation runs automatically: wait and read state; only awaiting_confirm needs a separate flagged-item decision. Capture can include changes made while publication is in flight; after a completed snapshot, later working-project changes require republishing. Report completion only from observed state and review, never merely an accepted mutation response. For republish, compare snapshot_id and processing state with the prior observation. An unchanged snapshot may be a successful no-op when current content is already served, or the old version while work is in flight; do not infer pending from an unchanged ID. Report observed state and any attribution uncertainty; neither a new snapshot nor current state is a per-call receipt.

  • Destructive

    Remove background

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

  • Destructive

    Remove project asset

    Remove only this placement_id from the project. Requires confirm_remove=true and explicit user authorization. Does not delete or physically purge the underlying uploaded file or job. Do not retry uncertain outcomes automatically.

  • Destructive

    Rename website

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

  • Destructive

    Sandbox exec

    Execute a shell command in a remote Higgsfield cloud Linux sandbox — NOT your local machine or the client's own shell. Use it for Higgsfield media workflows and website_repo_access checkouts that require the hosted toolchain. Do not use it to inspect a local repository, install desktop software, or control applications on the user's computer. 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, and packaging that dedicated Higgsfield tools do not cover. The sandbox is isolated per user. Existing sessions keep their assigned backend. E2B pauses with process memory; Modal preserves workspace files but not processes or RAM after replacement. Export important files within 24 hours of last use. A result with sandbox_created:true indicates a new sandbox, so files from earlier calls are not present; re-download missing 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 is bounded to 15 minutes; follow the lifetime and polling guidance in the command result. Set restart:true to discard the sandbox and start clean. Set size:"xl" only for the heaviest CPU work, such as a final multi-job video render; omit it for downloads, probes, edits, polling and inspection. An XL request may move the workspace to a new larger sandbox (files kept, running processes not), and the XL sandbox shuts down about a minute after its work finishes. For actual visual inspection, pass image_paths (up to 4 PNG/JPEG paths, <=512 KiB total) with a foreground command: images are returned natively to the model, not as text or URLs. With background work, wait for completion then use a foreground poll with image_paths before its lease expires. No upload is needed for inspection. The command limit is 128000 characters including signed URLs; keep upload batches small and use installed scripts. 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.

  • Destructive

    Save project publication preview

    Save publication metadata and prepare Cinema preview data. This does not open a rendered preview; only report a link if one is actually returned. This is a MUTATION and may immediately change existing public metadata. First read current settings and disclose the effective resulting prompts/canvas/discovery visibility for user approval. A published project returns its current snapshot, not a private frozen republish draft. Obtain explicit user approval through the MCP host before invoking this tool. The host owns its approval policy; the server cannot independently verify a human decision. Do not invoke based only on inferred intent. After an uncertain response, stop and read get_project_publication to observe current state. There is no per-operation receipt or automatic replay guarantee; do not blindly repeat a publication mutation. The private working-project name, public publication title (settings.name), and URL slug (settings.slug) are distinct; never infer a title or slug change from a working-project rename. For a share-link request, preserve any existing slug; prepare a nonempty URL-safe slug in the proposal only when absent or when the user requests a URL change, before approval and verify public_url after completion. show_canvas does not establish whether chats are hidden; no separate chat-privacy control or complete composition inventory is available, so do not promise that chats are excluded. Pending moderation runs automatically: wait and read state; only awaiting_confirm needs a separate flagged-item decision. Capture can include changes made while publication is in flight; after a completed snapshot, later working-project changes require republishing. Report completion only from observed state and review, never merely an accepted mutation response. For republish, compare snapshot_id and processing state with the prior observation. An unchanged snapshot may be a successful no-op when current content is already served, or the old version while work is in flight; do not infer pending from an unchanged ID. Report observed state and any attribution uncertainty; neither a new snapshot nor current state is a per-call receipt.

  • Destructive

    Scene builder 3d apply scene operations

    Submit a batch of viewport edits with stable operation IDs and inspected scene/entity versions. Widget-only. Acceptance precedes GLB checkpointing. On a conflict or uncertain submission, reconcile through scene_builder_3d_get_collaboration before retrying; never blindly repeat edits under new IDs.

  • Destructive

    Scene builder 3d run python

    Commit 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. REVISION_CONFLICT rejects the submission: do not poll that operation ID. A successful mutation advances `revisionAfter`. This worker pins Blender 5.2: use `BLENDER_EEVEE`, `BLENDER_WORKBENCH`, or `CYCLES`, not `BLENDER_EEVEE_NEXT`. Code is capped at 256 KiB, and execution and checkpoint/export must fit the configured worker deadline; keep renders small and split expensive work into coherent edits. Do not invent texture paths or fetch external files from Blender; use `scene_builder_3d_import_asset` for models. Successful execution does not establish visual correctness. Render from the delivery camera, publish the image through `artifacts`, retrieve it with `scene_builder_3d_get_artifact`, and inspect it before claiming completion. If visual inspection is unavailable, state what remains unverified. Use `scene_builder_3d_get_glb` or `scene_builder_3d_get_blend` when the user needs the committed files. Before building or editing a scene, load get_preset_instructions with { preset: "/3d-jutsu" } once for the full workflow, runtime limits and scene-building references. Finish each completed scene creation, edit, or import task by calling `scene_builder_3d_show_scene` once as the final scene inspection/edit call of that review phase, 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. Show an unchanged revision only once. Authorized generation and status calls may follow; later feedback or a verified mismatch can reopen scene editing. Verify and show the corrected revision at its next review boundary. This shows the result to the user; a text summary or download link alone does not finish scene delivery.

  • Destructive

    Unpublish project

    Request unpublishing under Cinema semantics after explicit user approval. Does not delete the private project or source files. No snapshot compare-and-swap binding is promised. This is not cancelling a pending review. Obtain explicit user approval through the MCP host before invoking this tool. The host owns its approval policy; the server cannot independently verify a human decision. Do not invoke based only on inferred intent. After an uncertain response, stop and read get_project_publication to observe current state. There is no per-operation receipt or automatic replay guarantee; do not blindly repeat a publication mutation. The private working-project name, public publication title (settings.name), and URL slug (settings.slug) are distinct; never infer a title or slug change from a working-project rename. For a share-link request, preserve any existing slug; prepare a nonempty URL-safe slug in the proposal only when absent or when the user requests a URL change, before approval and verify public_url after completion. show_canvas does not establish whether chats are hidden; no separate chat-privacy control or complete composition inventory is available, so do not promise that chats are excluded. Pending moderation runs automatically: wait and read state; only awaiting_confirm needs a separate flagged-item decision. Capture can include changes made while publication is in flight; after a completed snapshot, later working-project changes require republishing. Report completion only from observed state and review, never merely an accepted mutation response. For republish, compare snapshot_id and processing state with the prior observation. An unchanged snapshot may be a successful no-op when current content is already served, or the old version while work is in flight; do not infer pending from an unchanged ID. Report observed state and any attribution uncertainty; neither a new snapshot nor current state is a per-call receipt.

  • Destructive

    Update project

    Update shared project metadata only. Omitted fields stay unchanged; null clears nullable fields. Does not change Supercomputer configuration. Inspect get_project capabilities when permissions are unclear.

  • Destructive

    Update project publication

    Save partial Cinema publication settings. This may immediately change public metadata or visibility; it is not always a private draft. Read current settings and disclose the effective resulting prompts/canvas/discovery visibility before user approval. Omission leaves fields unchanged and null follows Cinema clearing semantics. Obtain explicit user approval through the MCP host before invoking this tool. The host owns its approval policy; the server cannot independently verify a human decision. Do not invoke based only on inferred intent. After an uncertain response, stop and read get_project_publication to observe current state. There is no per-operation receipt or automatic replay guarantee; do not blindly repeat a publication mutation. The private working-project name, public publication title (settings.name), and URL slug (settings.slug) are distinct; never infer a title or slug change from a working-project rename. For a share-link request, preserve any existing slug; prepare a nonempty URL-safe slug in the proposal only when absent or when the user requests a URL change, before approval and verify public_url after completion. show_canvas does not establish whether chats are hidden; no separate chat-privacy control or complete composition inventory is available, so do not promise that chats are excluded. Pending moderation runs automatically: wait and read state; only awaiting_confirm needs a separate flagged-item decision. Capture can include changes made while publication is in flight; after a completed snapshot, later working-project changes require republishing. Report completion only from observed state and review, never merely an accepted mutation response. For republish, compare snapshot_id and processing state with the prior observation. An unchanged snapshot may be a successful no-op when current content is already served, or the old version while work is in flight; do not infer pending from an unchanged ID. Report observed state and any attribution uncertainty; neither a new snapshot nor current state is a per-call receipt.

Not supported

  • Buying plans or credits on your behalf: billing tools only show checkout links, and purchases need your click in Higgsfield's own widget
  • Reading website secret values (only secret names are listed)
  • Writing to a Higgsfield website's database (database access is read-only)

Example prompts

  • Generate four product shots of our new water bottle on a beach at sunset and show me the cost first.
  • Turn this 60-second clip into vertical shorts in the Amber Drift style.
  • Research our brand from our website in Ads Studio and quote ads for our top three products.
  • Upscale yesterday's best video generation to 4K and dub it into Spanish.

Get started

  1. Open Space settings → Connections and search for Higgsfield.
  2. Connect your account and add the connection to the Space.
  3. Ask for what you need in any thread in that Space.

See How connections work for access and permissions, or browse all integrations.