diff --git a/skills/.curated/higgsfield-generate/LICENSE.txt b/skills/.curated/higgsfield-generate/LICENSE.txt new file mode 100644 index 00000000..54beb798 --- /dev/null +++ b/skills/.curated/higgsfield-generate/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Higgsfield AI + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/.curated/higgsfield-generate/SKILL.md b/skills/.curated/higgsfield-generate/SKILL.md new file mode 100644 index 00000000..c1734786 --- /dev/null +++ b/skills/.curated/higgsfield-generate/SKILL.md @@ -0,0 +1,154 @@ +--- +name: higgsfield-generate +description: >- + Generate images and videos with Higgsfield AI through the Higgsfield MCP + server, including general generation, visual edits, image-to-video, media + references, Soul-aware generation, Marketing Studio ads, products, avatars, + hooks/settings, and ad references. Use for images, videos, animations, + UGC/product-demo/brand clips, or avatar/product-based ads. Not for Soul + training, product photoshoots, marketplace cards, chat, or TTS. +--- + +# Higgsfield Generate + +Use the Higgsfield MCP server as the primary interface for image/video generation and Marketing Studio workflows. + +## MCP Tools + +- `models_explore` — list, search, recommend, or inspect model schemas. +- `generate_image` — submit image jobs. +- `generate_video` — submit video jobs. +- `show_marketing_studio` — browse/create/fetch avatars, products, webproducts, presets, hooks, settings, and ad references. +- `show_generations`, `job_status`, `job_display` — browse, poll, and display generation results. +- `media_upload`, `media_confirm` — prepare local image, video, or audio files for MCP generation. + +If MCP tools are unavailable, tell the user that the Higgsfield MCP dependency is missing or not connected. Do not silently switch to shell commands unless the user explicitly asks for them. + +## MCP setup + +If the Higgsfield MCP server is not connected, ask the user whether to add it: + +```bash +codex mcp add higgsfield --url https://mcp.higgsfield.ai/mcp +codex mcp login higgsfield +``` + +After successful login, the user may need to restart Codex before retrying the task. + +## UX Rules + +1. Be concise. Return ready result URLs or a short status summary. +2. Do not expose raw JSON unless the user asks. +3. Detect the user's language and respond in it. MCP model IDs and parameter names stay English. +4. Ask one missing-input question at a time; otherwise pick a strong default model. +5. Do not pre-estimate cost or optimize for cheaper models unless the user asks. +6. For non-terminal jobs, use `job_status` with the returned job id and respect `poll_after_seconds` if present. + +## Generic Generation + +1. Pick a model. Use `models_explore` with `action: "recommend"` when uncertain, then `action: "get"` for constraints. + + Image defaults: + - Product photoshoot / Pinterest / hero banner / ad pack / virtual try-on → use `higgsfield-product-photoshoot`, not this skill. + - Product concept, package, label text, graphic design, UI, banners, typography → `gpt_image_2`. + - Character, cartoon, stylized, or reference-driven image → `nano_banana_2`. + - Soul Character id from `higgsfield-soul-id` → `soul_2` for stills, `soul_cinematic` for cinematic stills. + - Branded ad image with avatar/product context → `marketing_studio_image`. + - Default general image → `gpt_image_2`. + + Video defaults: + - Ads, UGC, product demos, unboxing, TV spots, branded product clips → `marketing_studio_video`. + - Serious general video, image-to-video, motion-heavy, multi-shot, 4–15s → `seedance_2_0`. + - Simpler single-plane video when cost matters → `kling3_0`. + - Highest cinema-grade video → `cinematic_studio_3_0`. + - Fast batch / volume → `veo3_1_lite`. + +2. Prepare media. + - For HTTPS URLs, previous job IDs, or existing media IDs, pass them in `params.medias`. + - For local files, call `media_upload`, upload bytes to the returned presigned URL(s), then call `media_confirm`. Use confirmed media IDs in `params.medias`. + - Use the model's declared roles from `models_explore`: `image`, `start_image`, `end_image`, `video`, or `audio`. + +3. Submit with `generate_image` or `generate_video`. + +```json +{ + "params": { + "model": "gpt_image_2", + "prompt": "neon city at dusk, cinematic reflections", + "aspect_ratio": "16:9" + } +} +``` + +```json +{ + "params": { + "model": "seedance_2_0", + "prompt": "camera slowly dollies in, soft morning light", + "duration": 12, + "aspect_ratio": "16:9", + "medias": [{ "value": "", "role": "start_image" }] + } +} +``` + +4. Deliver the result URL when completed. If the response is pending, poll with `job_status`. + +## Marketing Studio + +Use Marketing Studio for branded ads, avatar/product campaigns, UGC clips, product demos, and Click-to-Ad flows. + +### Product Or Webproduct + +- Existing library: `show_marketing_studio` with `action: "list"`, `type: "product"` or `type: "webproduct"`. +- Product URL: `show_marketing_studio` with `action: "fetch"` and `url`. +- Uploaded product images: upload/confirm local media first, then `show_marketing_studio` with `action: "create"`, `type: "product"`, `title`, and `medias`. +- App Store / Play Store / SaaS pages: use `type: "webproduct"` when the ad promotes the app/site instead of one physical item. + +For URL-driven Click-to-Ad, call `show_marketing_studio(action: "fetch")`, then immediately follow the returned `next_step` and call `generate_video` with those exact params. + +### Avatars + +- Presets/custom avatars: `show_marketing_studio` with `action: "list"`, `type: "avatar"`. +- Custom avatar from local media: upload/confirm the image, then `show_marketing_studio` with `action: "create"`, `type: "avatar"`, and `avatars`. +- For UGC modes, an avatar is optional if the brief only needs a generic person; pass one when the user wants a specific presenter. + +### Hooks, Settings, And Modes + +- Presets: `show_marketing_studio` with `action: "presets"`. +- Hooks: `show_marketing_studio` with `action: "list"`, `type: "hook"`. +- Settings: `show_marketing_studio` with `action: "list"`, `type: "setting"`. +- Pass selected IDs to `generate_video` as `hook_id` and/or `setting_id`. +- Hooks/settings are valid only for Marketing Studio modes listed in `marketing-modes.md`. +- Do not combine `hook_id`/`setting_id` with `ad_reference_id`. + +### Ad References + +Use ad references when the user says "make a video like this", "copy this ad style", "use this clip as reference", or similar. + +1. For a local reference video, use `media_upload` and `media_confirm` with type `video`. +2. Call `show_marketing_studio` with `action: "create"`, `type: "ad_reference"`, and `video_input_id`; optionally bind one avatar and/or one product. +3. Follow the returned `next_step` when present. It includes `ad_reference_id` for `generate_video`. +4. If the user wants to refine the extracted concept, use `show_marketing_studio` with `action: "update"`, `type: "ad_reference"`, and edited concept fields. + +## Errors + +- Missing prompt → ask for the prompt. +- Invalid enum or unknown param → call `models_explore(action: "get", model_id: ...)` and retry with supported params. +- Auth failure → tell the user to connect/authenticate the Higgsfield MCP server. +- Failed generation / safety status → briefly explain and ask for a safer revision. +- Upload issue → retry `media_upload`/`media_confirm`; local paths cannot be passed directly to generation tools. + +## Reference Docs + +Load on demand: + +- `references/model-catalog.md` — picking models and checking schemas. +- `references/media-inputs.md` — MCP media upload and role handling. +- `references/prompt-engineering.md` — prompt patterns. +- `references/troubleshooting.md` — MCP errors and retry handling. +- `references/marketing-avatars.md` — avatar workflows. +- `references/marketing-products.md` — product and webproduct workflows. +- `references/marketing-setup-items.md` — hooks/settings. +- `references/marketing-ad-references.md` — ad reference videos. +- `references/marketing-modes.md` — Marketing Studio modes. diff --git a/skills/.curated/higgsfield-generate/agents/openai.yaml b/skills/.curated/higgsfield-generate/agents/openai.yaml new file mode 100644 index 00000000..95adc1ad --- /dev/null +++ b/skills/.curated/higgsfield-generate/agents/openai.yaml @@ -0,0 +1,13 @@ +interface: + display_name: "Higgsfield Generate" + short_description: "Generate images, videos, and ads" + brand_color: "#D1FE17" + default_prompt: "Use $higgsfield-generate to generate an image or video with Higgsfield AI." + +dependencies: + tools: + - type: "mcp" + value: "higgsfield" + description: "Higgsfield AI MCP server for image/video generation, Marketing Studio, media, jobs, and Soul Characters" + transport: "streamable_http" + url: "https://mcp.higgsfield.ai/mcp" diff --git a/skills/.curated/higgsfield-generate/references/marketing-ad-references.md b/skills/.curated/higgsfield-generate/references/marketing-ad-references.md new file mode 100644 index 00000000..916b01c0 --- /dev/null +++ b/skills/.curated/higgsfield-generate/references/marketing-ad-references.md @@ -0,0 +1,71 @@ +# Marketing Studio Ad References + +Ad references are reusable inspiration videos for "make a video like this" workflows. They extract a reference clip's scenario, pacing, hook, narration style, and composition so `marketing_studio_video` can follow it. + +## When To Use + +Use an ad reference when the user says: + +- "Make a video like this." +- "Recreate this ad." +- "Use this clip as a reference." +- "Copy the structure/style of this product video." + +Do not combine ad references with hooks/settings. Pick either: + +- Reference-driven: `ad_reference_id`. +- Composed setup: `hook_id` and/or `setting_id`. + +## Create From Local Video + +1. Call `media_upload` for the local video. +2. Upload bytes to the returned URL. +3. Call `media_confirm` with `type: "video"`. +4. Call `show_marketing_studio`: + +```json +{ + "action": "create", + "type": "ad_reference", + "video_input_id": "" +} +``` + +Optionally bind one avatar and/or one product: + +```json +{ + "action": "create", + "type": "ad_reference", + "video_input_id": "", + "avatars": [{ "id": "", "type": "preset" }], + "product_ids": [""] +} +``` + +The response may include `next_step`; follow it to call `generate_video` with `ad_reference_id`. + +## List Or Inspect + +Use `show_marketing_studio`: + +```json +{ "action": "list", "type": "ad_reference", "size": 20 } +``` + +The response includes status and processed reference metadata. A reference is usable when status is completed. + +## Edit Extracted Concept + +After analysis, the user can refine the extracted concept: + +```json +{ + "action": "update", + "type": "ad_reference", + "ad_reference_id": "", + "edited_concept_text": "Keep the same pacing, but make the hook focus on battery life." +} +``` + +Then call `generate_video` with the same `ad_reference_id`. diff --git a/skills/.curated/higgsfield-generate/references/marketing-avatars.md b/skills/.curated/higgsfield-generate/references/marketing-avatars.md new file mode 100644 index 00000000..ff0cb493 --- /dev/null +++ b/skills/.curated/higgsfield-generate/references/marketing-avatars.md @@ -0,0 +1,59 @@ +# Avatars + +Marketing Studio avatars are presenters for ads and UGC-style videos. + +## Preset Vs Custom + +| | Preset | Custom | +|---|---|---| +| Source | Curated by Higgsfield | User uploaded | +| Best for | Fast generic ads | Founder, employee, creator, brand-specific face | +| Creation | Already available | Requires media upload and create step | + +## Listing + +Call `show_marketing_studio`: + +```json +{ "action": "list", "type": "avatar", "size": 20 } +``` + +Use `search` to narrow large libraries. + +## Creating A Custom Avatar + +1. Upload/confirm one image with `media_upload` and `media_confirm`. +2. Call `show_marketing_studio`: + +```json +{ + "action": "create", + "type": "avatar", + "avatars": [ + { + "name": "Founder", + "medias": [ + { "value": "", "role": "image", "url": "", "type": "media_input" } + ] + } + ] +} +``` + +Avatar media should be an image. If the MCP response says a URL is required for a media input, include the CDN URL returned by the upload flow. + +## Passing To Generation + +For `generate_video` with `model: "marketing_studio_video"`, pass: + +```json +{ + "params": { + "model": "marketing_studio_video", + "prompt": "organic UGC product review", + "avatars": [{ "id": "", "type": "preset" }] + } +} +``` + +Use `type: "custom"` for user-created avatars. For UGC modes, an avatar can be omitted when a generic presenter is acceptable. diff --git a/skills/.curated/higgsfield-generate/references/marketing-modes.md b/skills/.curated/higgsfield-generate/references/marketing-modes.md new file mode 100644 index 00000000..351e5f60 --- /dev/null +++ b/skills/.curated/higgsfield-generate/references/marketing-modes.md @@ -0,0 +1,45 @@ +# Marketing Studio Modes + +Use `mode` in `generate_video` params for `marketing_studio_video`. + +| Mode slug | Human-readable label | Hook/setting | Best for | +|---|---|---|---| +| `ugc` | UGC | Yes | Default casual, organic presenter content. | +| `ugc_how_to` | Tutorial | Yes | Explainer or "how to use this" ad. | +| `ugc_unboxing` | Unboxing | Yes | Package opening and reveal. | +| `product_showcase` | Product Showcase | No | Polished product-first highlight. | +| `product_review` | Product Review | Yes | Presenter opinion/review. | +| `tv_spot` | TV Spot | No | Broadcast-style commercial. | +| `wild_card` | Wild Card | No | Experimental creative direction. | +| `ugc_virtual_try_on` | UGC Virtual Try On | Yes | Organic clothing/accessory try-on. | +| `virtual_try_on` | Pro Virtual Try On | No | Polished try-on. | + +Default when unspecified: `ugc`. + +## Picking Flow + +- Real-person phone-shot feel → `ugc`, `ugc_how_to`, `ugc_unboxing`, or `ugc_virtual_try_on`. +- Polished broadcast commercial → `tv_spot`. +- Product-first, less presenter → `product_showcase`. +- Opinion / testimonial → `product_review`. +- Clothing/accessory try-on → `ugc_virtual_try_on` or `virtual_try_on`. +- Surprise / experimental → `wild_card`. + +## Common Params + +- `aspect_ratio`: `auto`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. +- `duration`: integer seconds; inspect current bounds with `models_explore(action: "get", model_id: "marketing_studio_video")`. +- `resolution`: `480p` or `720p`. +- `generate_audio`: boolean. +- `avatars`: array of `{ "id": "...", "type": "preset" | "custom" }`. +- `product_ids`: array of product UUIDs. +- `hook_id`, `setting_id`: optional setup item UUIDs. +- `ad_reference_id`: optional ad-reference UUID; do not combine with hooks/settings. +- `medias`: optional references with role `image`, `start_image`, or `end_image`. +- `url`: Click-to-Ad product/webproduct URL. + +## URL-Driven Click-To-Ad + +1. Call `show_marketing_studio` with `action: "fetch"` and `url`. +2. Follow `next_step` exactly when present; it calls `generate_video` with the right URL/type params. +3. If no `next_step` is returned, call `generate_video` with `model: "marketing_studio_video"` and the same `url`. diff --git a/skills/.curated/higgsfield-generate/references/marketing-products.md b/skills/.curated/higgsfield-generate/references/marketing-products.md new file mode 100644 index 00000000..e5190266 --- /dev/null +++ b/skills/.curated/higgsfield-generate/references/marketing-products.md @@ -0,0 +1,61 @@ +# Products + +Marketing Studio supports physical products and webproducts. + +## Product Vs Webproduct + +- `product` — a specific physical or sellable item. Use for a SKU, product page, bottle, clothing item, gadget, supplement, etc. +- `webproduct` — an app, SaaS, website, or service. Use for App Store / Play Store pages, landing pages, or company homepages where no single item should be featured. + +When unsure, default to `product`. App Store and Play Store URLs should be `webproduct`. + +## Fetch From URL + +Call `show_marketing_studio`: + +```json +{ + "action": "fetch", + "url": "https://shop.example.com/sneakers", + "type": "product" +} +``` + +Omit `type` when the URL should be inferred. The response renders the library widget and may include `next_step`; for Click-to-Ad, follow `next_step` immediately. + +## Create From Uploaded Media + +1. Upload/confirm product images with `media_upload` and `media_confirm`. +2. Call `show_marketing_studio`: + +```json +{ + "action": "create", + "type": "product", + "title": "AeroRun Pro", + "description": "Lightweight running shoe", + "medias": [ + { "value": "", "role": "image", "url": "", "type": "media_input" } + ] +} +``` + +If `title` is omitted, the server derives one from media filenames or URLs. + +## Manual Webproduct + +Use `show_marketing_studio` with `action: "create"` and `type: "webproduct"`. Useful fields include `title`, `subtitle`, `description`, `webproduct_url`, `favicon_url`, and `webproduct_medias`. + +## Listing + +Use `show_marketing_studio` with: + +```json +{ "action": "list", "type": "product" } +``` + +or: + +```json +{ "action": "list", "type": "webproduct" } +``` diff --git a/skills/.curated/higgsfield-generate/references/marketing-setup-items.md b/skills/.curated/higgsfield-generate/references/marketing-setup-items.md new file mode 100644 index 00000000..31e6d261 --- /dev/null +++ b/skills/.curated/higgsfield-generate/references/marketing-setup-items.md @@ -0,0 +1,47 @@ +# Marketing Studio Hooks And Settings + +Hooks and settings are optional building blocks for `marketing_studio_video`. + +- Hook (`hook_id`) controls the opening angle or ad mechanic. +- Setting (`setting_id`) controls environment or scene context. +- They are supported by `marketing_studio_video`, not `marketing_studio_image`. +- They are mutually exclusive with `ad_reference_id`. + +## Discover Items + +Hooks: + +```json +{ "action": "list", "type": "hook", "size": 20 } +``` + +Settings: + +```json +{ "action": "list", "type": "setting", "size": 20 } +``` + +Use `search` when the list is large. Responses include `items`, pagination cursor fields, and each setup item's `id`, `name`, `prompt`, `source`, and metadata. + +## Generate With Setup Items + +Pass one or both IDs to `generate_video`: + +```json +{ + "params": { + "model": "marketing_studio_video", + "prompt": "casual UGC ad for the product", + "mode": "ugc", + "product_ids": [""], + "hook_id": "", + "setting_id": "", + "duration": 15, + "aspect_ratio": "9:16" + } +} +``` + +When using a hook, include product context whenever possible; hooks are designed to pivot into a product pitch. + +Setup items are valid only for: `ugc`, `ugc_how_to`, `ugc_unboxing`, `product_review`, and `ugc_virtual_try_on`. See `marketing-modes.md`. diff --git a/skills/.curated/higgsfield-generate/references/media-inputs.md b/skills/.curated/higgsfield-generate/references/media-inputs.md new file mode 100644 index 00000000..44c8b56d --- /dev/null +++ b/skills/.curated/higgsfield-generate/references/media-inputs.md @@ -0,0 +1,71 @@ +# Media Inputs + +Use MCP media inputs for reference images, videos, and audio. + +## Local Files + +Local file paths cannot be passed directly to `generate_image` or `generate_video`. + +1. Call `media_upload` with `files` and content types. +2. Upload bytes to each returned `upload_url` using the returned instructions or an equivalent PUT request. +3. Call `media_confirm` with `type: "image"`, `"video"`, or `"audio"`. +4. Use the confirmed `media_id` as `params.medias[].value`. + +## Existing References + +These can be passed directly as `params.medias[].value`: + +- Confirmed media IDs from `media_confirm`. +- Previous generation job IDs. +- HTTPS media URLs when the receiving MCP tool supports URL ingestion. + +## Roles + +Each model declares accepted media roles. Check with `models_explore` using `action: "get"`. + +| Model family | Common roles | Notes | +|---|---|---| +| Most image models | `image` | One or more references. | +| `seedance_2_0` | `image`, `start_image`, `end_image`, `video`, `audio` | Audio is a media role, not a separate audio-generation flag. | +| `kling3_0` | `start_image`, `end_image` | First/last frame transitions. | +| `kling2_6` | `start_image` | Single frame anchor. | +| `veo3_1` | `start_image` | Usually max one reference. | +| `veo3` | `image` | Single image-to-video reference. | +| `marketing_studio_video` | `image`, `start_image`, `end_image` | Product/avatar/ad data is passed through dedicated params. | +| Text-only models | none | Do not pass media. | + +## Example Param Shapes + +Image reference: + +```json +{ + "params": { + "model": "nano_banana_2", + "prompt": "transform into watercolor style", + "medias": [{ "value": "", "role": "image" }] + } +} +``` + +Image-to-video with audio reference: + +```json +{ + "params": { + "model": "seedance_2_0", + "prompt": "person speaking naturally to camera", + "duration": 8, + "medias": [ + { "value": "", "role": "start_image" }, + { "value": "", "role": "audio" } + ] + } +} +``` + +## Mismatches + +- If a model rejects a role, call `models_explore(action: "get")` and choose one of its declared roles. +- If a model is text-only, remove `medias`. +- If multiple references fail, retry with one reference first, then add more. diff --git a/skills/.curated/higgsfield-generate/references/model-catalog.md b/skills/.curated/higgsfield-generate/references/model-catalog.md new file mode 100644 index 00000000..eef5c00b --- /dev/null +++ b/skills/.curated/higgsfield-generate/references/model-catalog.md @@ -0,0 +1,71 @@ +# Model Catalog + +Use `models_explore` as the source of truth for current model IDs, accepted parameters, media roles, aspect ratios, and durations. + +Recommended quick defaults: + +- Images/design/text: `gpt_image_2`. +- Video: `seedance_2_0`. +- Character/stylized/reference image work: `nano_banana_2`. +- Soul-aware image work: `soul_2` or `soul_cinematic`. +- Ads/UGC/product demos: `marketing_studio_video` or `marketing_studio_image`. + +## Image Models + +| Model | Provider | What it's for | +|---|---|---| +| `gpt_image_2` | OpenAI | Default high-fidelity image generation, graphic design, UI, banners, typography, and on-image text. | +| `nano_banana_2` | Google | Character, cartoon, stylized, and reference-driven image work. | +| `soul_2` | Higgsfield | Aesthetic UGC, fashion editorial, lifestyle character generation; accepts Soul Character IDs. | +| `soul_cinematic` | Higgsfield | Cinematic stills with Soul identity support. | +| `soul_cast` | Higgsfield | Distinctive text-only personas. | +| `soul_location` | Higgsfield | Environments and no-person locations. | +| `seedream_v4_5` | Bytedance | Vector illustrations and complex instruction-based edits. | +| `z_image` | Tongyi-MAI | Fast drafts and iteration. | +| `flux_2` / `flux_kontext` | Black Forest Labs | Prompt adherence, style transfer, typography remix. | +| `marketing_studio_image` | Higgsfield | Branded image ads with avatar/product context. | + +## Video Models + +| Model | Provider | What it's for | +|---|---|---| +| `seedance_2_0` | Bytedance | Default serious video, image-to-video, multi-shot, strong identity consistency. | +| `kling3_0` | Kling | Simpler single-plane scenes, lower-cost motion work. | +| `cinematic_studio_3_0` | Higgsfield | Highest-fidelity cinema-grade video. | +| `marketing_studio_video` | Higgsfield | Ads, UGC, unboxing, product demos, TV spots, Click-to-Ad. | +| `veo3_1_lite` | Google | Fast batch and volume. | +| `veo3_1` / `veo3` | Google | Cinematic video with stricter format constraints. | +| `minimax_hailuo` | Hailuo | Budget physics-heavy clips. | +| `wan2_7` / `wan2_6` | Wan | Stylized or experimental creative. | + +## Picking Flow + +Image: + +1. Product photoshoot / Pinterest / hero banner / ad pack / virtual try-on / restyle → use `higgsfield-product-photoshoot`. +2. Product concept, package, label text, graphic design, UI, banner → `gpt_image_2`. +3. Branded ad image with avatar/product context → `marketing_studio_image`. +4. Soul Character ID available → `soul_2` or `soul_cinematic`. +5. Character/cartoon/reference-driven image → `nano_banana_2`. +6. Environments/no-person scenes → `soul_location`. +7. Fast draft → `z_image`. +8. Default general image → `gpt_image_2`. + +Video: + +1. Ads, UGC, unboxing, product demos, branded commercial → `marketing_studio_video`. +2. Serious general video / image-to-video / multi-shot → `seedance_2_0`. +3. Simpler cheaper video → `kling3_0`. +4. Highest cinema-grade video → `cinematic_studio_3_0`. +5. Fast batch → `veo3_1_lite`. + +## Schema Checks + +Call `models_explore` with `action: "get"` before passing uncommon params. Use the returned schema for: + +- Aspect ratios. +- Duration bounds. +- Model-specific params. +- Accepted media roles. + +Do not invent model IDs or params. diff --git a/skills/.curated/higgsfield-generate/references/prompt-engineering.md b/skills/.curated/higgsfield-generate/references/prompt-engineering.md new file mode 100644 index 00000000..13360d04 --- /dev/null +++ b/skills/.curated/higgsfield-generate/references/prompt-engineering.md @@ -0,0 +1,47 @@ +# Prompt Engineering + +## Basics + +Higgsfield models reward concrete, sensory prompts. + +- Subject + setting + style: "a red fox curled in a snowy pine forest, golden hour, cinematic" +- Camera: lens, angle, framing, camera motion. +- Lighting: rim light, neon glow, moody backlight. +- Style/medium: photograph, anime, 3D render, watercolor. + +Keep prompts concise. Very long prompts can reduce adherence. + +## Image References + +When passing a reference image in `params.medias`, describe the transformation, not every visible detail. + +Bad: "a man with brown hair in a leather jacket holding coffee, made into anime" +Good: "transform into anime style, vibrant colors, soft cel shading" + +## Image-To-Video + +Use `role: "start_image"` when the image should anchor the first frame. Prompt the motion: + +- Camera motion: zooms in, dollies left, sweeping pan. +- Subject motion: the dancer spins, smoke rises slowly. +- Mood: handheld UGC, cinematic, polished commercial. + +Do not redescribe the static frame; the model already has it. + +## Positive Phrasing + +Most models do not need negative prompts. Phrase positively: + +- Instead of "no blur" → "tack sharp". +- Instead of "no people" → "uninhabited landscape". + +## Aspect Ratio Guidance + +- `16:9` — landscape, cinematic. +- `9:16` — vertical social. +- `1:1` — square, profile/icon. +- `4:3`, `3:4`, `21:9` — model dependent; inspect with `models_explore`. + +## Safety + +Avoid real public figures, sexual content, and trademarked characters unless the user clearly has rights and the request is allowed. diff --git a/skills/.curated/higgsfield-generate/references/troubleshooting.md b/skills/.curated/higgsfield-generate/references/troubleshooting.md new file mode 100644 index 00000000..889a3d3c --- /dev/null +++ b/skills/.curated/higgsfield-generate/references/troubleshooting.md @@ -0,0 +1,27 @@ +# Troubleshooting + +## MCP Auth + +- `Unauthorized` or auth challenge → ask the user to connect/authenticate the Higgsfield MCP server. +- The server advertises OAuth/device auth through `.well-known/oauth-protected-resource`; let the MCP host handle the flow. +- If auth succeeds but user data is empty, ask the user to confirm they are using the intended Higgsfield account/workspace. + +## Validation + +- Missing `prompt` → ask for a concise prompt. +- Invalid enum or unsupported field → call `models_explore(action: "get", model_id: ...)` and retry with declared params. +- Media role rejected → inspect the model's `medias` schema and change the role. +- Local file path rejected → use `media_upload`, upload bytes, then `media_confirm`; pass the resulting media ID. + +## Job Lifecycle + +- Non-terminal job → call `job_status`; respect `poll_after_seconds` if present. +- `failed` → try a safer or clearer prompt; mention the failure briefly. +- `nsfw` / `ip_detected` → content policy; ask for a safer revision. +- Timeout or transient server/network error → retry once, then report the request id if present. + +## Marketing Studio + +- Product fetch failed → ask for a clearer product URL or uploaded product images. +- Hook/setting rejected → confirm the selected `mode` supports setup items. +- Ad reference plus hook/setting rejected → choose one path: `ad_reference_id` or explicit hook/setting. diff --git a/skills/.curated/higgsfield-marketplace-cards/LICENSE.txt b/skills/.curated/higgsfield-marketplace-cards/LICENSE.txt new file mode 100644 index 00000000..54beb798 --- /dev/null +++ b/skills/.curated/higgsfield-marketplace-cards/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Higgsfield AI + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/.curated/higgsfield-marketplace-cards/SKILL.md b/skills/.curated/higgsfield-marketplace-cards/SKILL.md new file mode 100644 index 00000000..f61c1b49 --- /dev/null +++ b/skills/.curated/higgsfield-marketplace-cards/SKILL.md @@ -0,0 +1,79 @@ +--- +name: higgsfield-marketplace-cards +description: >- + Generate marketplace-ready product image cards via the Higgsfield CLI, + including compliant main images, secondary product images, infographics, + lifestyle listing shots, marketplace image sets, and A+ style modules. Not for + generic product photography, video ads, or Soul Character training. +--- + +# Marketplace Cards + +Create marketplace-ready product visuals with `higgsfield marketplace-cards create`. +The CLI first calls the backend enhancer, where marketplace rules and templates are kept private, then creates `nano_banana_2` jobs and prints result URLs. + +## Step 0 — Bootstrap + +1. If `higgsfield` is not on `$PATH`, ask the user whether to install the Higgsfield CLI with the official installer: `curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh`. +2. If `higgsfield account status` fails with authentication errors, ask the user to run `higgsfield auth login`. + +## UX Rules + +1. Respond in the user's language. +2. Ask at most one concise confirmation question before running. +3. Prefer a product image. If the user provides only text or a URL, proceed only when the product details are clear. +4. Do not write final image-generation prompts yourself. Backend enhancement owns that. +5. Final answer should contain only the ready image URLs and short labels. + +## Scope Selection + +Use `--scope` when the user asks for a common bundle: + +| Scope | Creates | +|---|---| +| `main` | 1 marketplace main image | +| `product-images` | main image + 5 secondary images | +| `aplus` | main image + 7 A+ modules | +| `full-set` | main image + 5 secondary images + 7 A+ modules | + +Use repeated `--asset` only for custom subsets: + +- `main_image` +- `infographic` +- `multi_angle` +- `detail_shot` +- `lifestyle` +- `whats_in_box` +- `aplus_hero_banner` +- `aplus_pain_points` +- `aplus_features` +- `aplus_ingredients` +- `aplus_efficacy` +- `aplus_how_to_use` +- `aplus_endorsement` + +## Command + +Build and run one `higgsfield marketplace-cards create` command from the user's request. + +For common bundles, use `--scope `, `--prompt ""`, optional repeated `--image `, and optional context flags: `--product_context`, `--brand_context`, `--category`, `--visual_style`. + +Examples to mirror when choosing arguments: + +- Product images: `higgsfield marketplace-cards create --scope product-images --prompt "sparkling peach lemonade can for marketplace listing" --image ./can.png --category "beverage"` +- Full set: `higgsfield marketplace-cards create --scope full-set --prompt "premium skincare serum, clean clinical marketplace visual system" --image ./serum.jpg --brand_context "minimal white and sage palette"` +- Custom subset: repeat `--asset`, for example `--asset main_image --asset infographic --asset lifestyle`. +- Existing completed main image job: use `--main-job ` with the requested secondary or A+ `--asset` values. + +## Delivery + +Print URLs with labels: + +```text +Marketplace cards ready: +- Main image: https://... +- Infographic: https://... +- Lifestyle: https://... +``` + +Avoid JSON, job IDs, internal model names, or enhanced prompt text unless the user explicitly asks. diff --git a/skills/.curated/higgsfield-marketplace-cards/agents/openai.yaml b/skills/.curated/higgsfield-marketplace-cards/agents/openai.yaml new file mode 100644 index 00000000..77f39845 --- /dev/null +++ b/skills/.curated/higgsfield-marketplace-cards/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Higgsfield Marketplace Cards" + short_description: "Create marketplace-ready image sets" + brand_color: "#D1FE17" + default_prompt: "Use $higgsfield-marketplace-cards to create marketplace-ready product image cards." diff --git a/skills/.curated/higgsfield-product-photoshoot/LICENSE.txt b/skills/.curated/higgsfield-product-photoshoot/LICENSE.txt new file mode 100644 index 00000000..54beb798 --- /dev/null +++ b/skills/.curated/higgsfield-product-photoshoot/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Higgsfield AI + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/.curated/higgsfield-product-photoshoot/SKILL.md b/skills/.curated/higgsfield-product-photoshoot/SKILL.md new file mode 100644 index 00000000..20d94c3f --- /dev/null +++ b/skills/.curated/higgsfield-product-photoshoot/SKILL.md @@ -0,0 +1,201 @@ +--- +name: higgsfield-product-photoshoot +description: >- + Generate brand-quality product images via the Higgsfield CLI product-photoshoot + prompt enhancement on GPT Image 2. Use for product photos, studio shots, + lifestyle scenes, Pinterest pins, hero banners, social carousels, ad creatives, + virtual try-on, conceptual product imagery, and restyles. Not for video ads, + marketplace cards, Soul training, or generic no-product generation. +--- + +# Product Photoshoot + +Brand-image generation via the `higgsfield product-photoshoot create` command. The CLI calls a backend prompt enhancer that holds mode-specific photography vocabulary and structural templates, then submits to `gpt_image_2` and returns image URLs. + +## Step 0 — Bootstrap + +Before any other command: + +1. If `higgsfield` is not on `$PATH`, ask the user whether to install the Higgsfield CLI with the official installer: + ```bash + curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh + ``` +2. If `higgsfield account status` fails with `Session expired` / `Not authenticated`, ask the user to run `higgsfield auth login` (interactive) and wait for confirmation. + +## UX Rules + +1. Be concise. Print only image URLs in the final reply. +2. Detect language, respond in it. Mode names and CLI flags stay English. +3. Ask at most 4 short questions before submitting. Use labeled options, never open-ended. +4. Skip questions whose answer is obvious from context (uploaded image, prior turn, brand memory). +5. Never write the gpt_image_2 prompt yourself — backend assembles it. +6. Polling is silent. Wait until URLs are ready, then deliver. + +## Modes + +| Mode | When user wants… | +|---|---| +| `product_shot` | Product on neutral / studio / catalog background | +| `lifestyle_scene` | Product in real-world environment, hands, action, atmosphere | +| `closeup_product_with_person` | Tight crop with hands / partial face — beauty application, holding, demonstrating | +| `moodboard_pin` | Vertical 2:3 Pinterest-native aesthetic, moodboard feel | +| `hero_banner` | Wide-format website / email / campaign header | +| `social_carousel` | 3–10 connected slides for IG / LinkedIn / Facebook | +| `ad_creative_pack` | Coordinated pack of static ad variants for Meta / TikTok / Pinterest / Google Ads | +| `virtual_model_tryout` | Product worn or used by an AI-rendered model | +| `conceptual_product` | Surreal / CGI-style / levitating / splash / sculptural product | +| `restyle` | Transform an existing image's aesthetic, mood, or seasonal context | + +## Mode selection + +Pick by intent, not surface keyword. When two modes could apply, prefer the more specific one. + +- product + neutral / clean / white / studio / catalog / Shopify → `product_shot` +- product + scene / in use / kitchen / outdoor / cafe / gym → `lifestyle_scene` +- hands holding / face with product / beauty application / demonstrating → `closeup_product_with_person` +- Pinterest, pin, vertical pin → `moodboard_pin` +- hero, banner, website header, landing page, email header, wide format → `hero_banner` +- carousel, slide post, multi-slide, swipeable → `social_carousel` +- ads, ad pack, paid social, Meta / TikTok / Pinterest ads → `ad_creative_pack` +- model wearing, virtual try-on, on body, fashion shoot, lookbook → `virtual_model_tryout` +- levitating, floating, splash, frozen motion, surreal, CGI, sculptural → `conceptual_product` +- modify EXISTING image's aesthetic, mood, season — without changing subject → `restyle` + +Tie-breakers: +- "Pinterest pin of my product on a kitchen counter" → `moodboard_pin` (Pinterest is the platform) +- "Hero banner showing my product in use" → `hero_banner` (banner format wins) +- "Carousel of my product in different scenes" → `social_carousel` (multi-slide wins) +- "Closeup of person applying my serum" → `closeup_product_with_person` (specific genre wins) + +## Pre-generation interview + +Ask 3–4 short questions before submitting. Always labeled options, never open-ended. Skip a question whose answer is obvious from context. + +### Type A — uploaded a product photo, "make me images / photoshoots" + +1. How many? `[1 / 3 / 5]` +2. What style/mood? `[Clean studio / Lifestyle / Conceptual / With a model / Other]` +3. Where will you use them? `[Shopify / Instagram / Pinterest / Paid ads / Website hero]` +4. Brand colors to match? (skip if obvious) + +### Type B — uploaded a product photo, named a use case + +E.g. "make ads for my product", "make a Pinterest pin", "make a hero banner". Mode is obvious. Ask only the gaps: + +1. How many? (if multi-output mode) +2. What's the offer / mood / hook? +3. Anything in particular to emphasize? + +### Type C — text only, no product photo + +1. Can you upload a product photo? (preferred — much higher fidelity) +2. If not, describe the product — category, packaging, color, distinctive features. +3. What style? (same options as Type A) +4. Where will you use it? + +### Type D — uploaded existing image, "redo / change vibe / different version" + +→ `restyle` + +1. What aesthetic? `[Clean girl / Cottagecore / Quiet luxury / Dark academia / Y2K / Other]` +2. Seasonal context? `[Christmas / Valentine's / Halloween / Black Friday / None]` +3. What to preserve, what to change? (only if ambiguous) + +### Type E — model wearing a product (fashion, accessories) + +→ `virtual_model_tryout` + +1. Model archetype? (suggest 2–3 based on brand audience) +2. Environment? `[Studio clean / Outdoor natural / Street style / Editorial / Home cozy]` +3. Framing? `[Full body / Three-quarter / Waist up / Closeup on product area]` + +### Type F — vague request, unclear subject + +E.g. "make me something cool for my brand". + +1. What product or topic? +2. Goal? `[Sell on a marketplace / Build awareness / Run paid ads / Update website]` +3. Upload a reference image? + +After answers → return to the relevant Type A–E. + +## Generation + +Single command. Backend assembles the final prompt and submits to `gpt_image_2`. URLs print on stdout. + +```bash +higgsfield product-photoshoot create \ + --mode \ + --prompt "" \ + [--image ]... \ + [--count <1-10>] \ + [--aspect_ratio ] +``` + +Examples: + +```bash +higgsfield product-photoshoot create \ + --mode lifestyle_scene \ + --prompt "bottle of cold-brew on a sunlit kitchen counter, IG feed" \ + --image bottle.jpg \ + --count 3 +``` + +```bash +higgsfield product-photoshoot create \ + --mode moodboard_pin \ + --prompt "vertical pin for my candle brand, cottagecore mood" \ + --image candle.jpg +``` + +```bash +higgsfield product-photoshoot create \ + --mode restyle \ + --prompt "Christmas version, quiet-luxury aesthetic" \ + --image existing-shot.jpg +``` + +## Image inputs + +`--image` accepts a local file path (auto-uploaded) OR an existing upload UUID. Repeat the flag for multiple references. + +## Multi-variant + +`--count 3` returns 3 distinct image URLs. Backend asks the enhancer to vary preset, lighting, angle, and palette across variants — they will not be paraphrased copies of one another. + +For `social_carousel` and `ad_creative_pack`, count = number of slides / variants in the pack. Backend locks the visual system across all slides automatically. + +## Aspect ratio + +Backend picks a sensible default per mode. Override with `--aspect_ratio` only if the user explicitly asks for a different one. Allowed values: `1:1`, `4:5`, `5:4`, `3:4`, `4:3`, `2:3`, `3:2`, `9:16`, `16:9`. + +## Resolution + +Use `2k` for every product-photoshoot job. + +## Delivering results + +Print the image URLs as a short bulleted list. No JSON, no IDs, no internal model names, no enhanced prompt text. If a job failed, mention it briefly with the failure status. + +``` +3 lifestyle shots ready: +- https://cdn.higgsfield.ai/.../job_abc.jpg +- https://cdn.higgsfield.ai/.../job_def.jpg +- https://cdn.higgsfield.ai/.../job_ghi.jpg +``` + +## What this skill does NOT do + +- Does not write gpt_image_2 prompts directly. Backend owns prompt assembly. +- Does not auto-pick a different image-gen model. Always `gpt_image_2`. +- Does not replace `higgsfield-generate` Marketing Studio for branded video / avatar workflows. +- Does not replace `higgsfield-generate` for raw text-to-image without a product or brand context. + +## Common mistakes to avoid + +- Asking more than 4 interview questions in a single message. +- Picking the wrong mode (e.g. `product_shot` when the user wants a Pinterest pin). +- Calling `higgsfield generate create gpt_image_2 --prompt ...` directly instead of `higgsfield product-photoshoot create` — bypasses the prompt enhancer and produces noticeably worse output. +- Pasting the assembled prompt back to the user — they want the URLs. +- Using a `--mode` value not in the table above. diff --git a/skills/.curated/higgsfield-product-photoshoot/agents/openai.yaml b/skills/.curated/higgsfield-product-photoshoot/agents/openai.yaml new file mode 100644 index 00000000..b76024a3 --- /dev/null +++ b/skills/.curated/higgsfield-product-photoshoot/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Higgsfield Product Photoshoot" + short_description: "Generate brand-quality product images" + brand_color: "#D1FE17" + default_prompt: "Use $higgsfield-product-photoshoot to create brand-quality product images from this product photo." diff --git a/skills/.curated/higgsfield-soul-id/LICENSE.txt b/skills/.curated/higgsfield-soul-id/LICENSE.txt new file mode 100644 index 00000000..54beb798 --- /dev/null +++ b/skills/.curated/higgsfield-soul-id/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Higgsfield AI + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/.curated/higgsfield-soul-id/SKILL.md b/skills/.curated/higgsfield-soul-id/SKILL.md new file mode 100644 index 00000000..69167473 --- /dev/null +++ b/skills/.curated/higgsfield-soul-id/SKILL.md @@ -0,0 +1,93 @@ +--- +name: higgsfield-soul-id +description: >- + Train a Higgsfield Soul Character through the Higgsfield MCP server for + identity-faithful generation from face photos. Use for reusable face + references, digital twins, avatars, or identity setup for generated images + and videos. Not for one-shot face swaps or non-photo character prompts. +--- + +# Higgsfield Soul Character + +Train a face-faithful identity model through the Higgsfield MCP server. Reuse the resulting Soul Character in Higgsfield generation. + +## MCP Tools + +- `show_characters` — list, train, and check Soul Characters with widget support. +- `media_upload`, `media_confirm` — prepare local face photos before training. +- `generate_image` — use a ready Soul Character with `model: "soul_2"` or `model: "soul_cinematic"`. + +If MCP tools are unavailable, tell the user that the Higgsfield MCP dependency is missing or not connected. Do not silently switch to shell commands unless the user explicitly asks for them. + +## MCP setup + +If the Higgsfield MCP server is not connected, ask the user whether to add it: + +```bash +codex mcp add higgsfield --url https://mcp.higgsfield.ai/mcp +codex mcp login higgsfield +``` + +After successful login, the user may need to restart Codex before retrying the task. + +## UX Rules + +1. Be concise. Say when training has started and when the Soul Character is ready. +2. Detect language and respond in it. MCP parameter names stay English. +3. Ask for the smallest missing set: name + 5–20 face photos. +4. Training takes minutes. Use status/list polling instead of repeated chat narration. + +## Training Workflow + +1. Get a short name for the character. +2. Get 5–20 clear face photos with varied angles and lighting. +3. For local files, call `media_upload`, upload bytes to the returned URL(s), then call `media_confirm` with `type: "image"`. +4. Call `show_characters`: + +```json +{ + "action": "train", + "name": "Alex", + "images": ["", "", "", "", ""] +} +``` + +5. Use `show_characters` with `action: "status"` or `action: "list"` until the character is ready. +6. Deliver the Soul Character name and id. + +## Use The Soul + +For personalized image generation, call `generate_image`: + +```json +{ + "params": { + "model": "soul_2", + "prompt": "editorial portrait in soft window light", + "soul_id": "", + "quality": "2k" + } +} +``` + +Use `soul_cinematic` instead when the user wants cinematic stills. + +## Listing Existing Souls + +Call `show_characters`: + +```json +{ "action": "list", "status": "ready", "size": 20 } +``` + +## Errors + +- Not authenticated → ask the user to connect/authenticate the Higgsfield MCP server. +- Plan/upgrade error → tell the user Soul training requires a paid plan. +- Too few/many photos → ask for 5–20 face photos. +- Training failed → ask for sharper, better-lit, more varied face photos. + +## Reference Docs + +- `references/photo-guide.md` — what photos work best. +- `references/troubleshooting.md` — common training failures. diff --git a/skills/.curated/higgsfield-soul-id/agents/openai.yaml b/skills/.curated/higgsfield-soul-id/agents/openai.yaml new file mode 100644 index 00000000..dcb4c137 --- /dev/null +++ b/skills/.curated/higgsfield-soul-id/agents/openai.yaml @@ -0,0 +1,13 @@ +interface: + display_name: "Higgsfield Soul Character" + short_description: "Train reusable face identity references" + brand_color: "#D1FE17" + default_prompt: "Use $higgsfield-soul-id to train a reusable Soul Character from these face photos." + +dependencies: + tools: + - type: "mcp" + value: "higgsfield" + description: "Higgsfield AI MCP server for Soul Characters, media upload, and generation" + transport: "streamable_http" + url: "https://mcp.higgsfield.ai/mcp" diff --git a/skills/.curated/higgsfield-soul-id/references/photo-guide.md b/skills/.curated/higgsfield-soul-id/references/photo-guide.md new file mode 100644 index 00000000..90ce6ef5 --- /dev/null +++ b/skills/.curated/higgsfield-soul-id/references/photo-guide.md @@ -0,0 +1,37 @@ +# Photo Guide + +What to upload for Soul training. + +## Quantity + +- Minimum 5, maximum 20. +- 8–12 is the sweet spot. + +## Content + +- Clear face, eyes visible. +- Single person per photo. +- No heavy filters, no sunglasses. + +## Variety + +Higher variety = better identity capture. + +- Multiple angles: front, 3/4 left, 3/4 right, slight up/down. +- Different lighting: indoor, outdoor, soft, harsh. +- Different expressions: neutral, smiling, talking. +- Different distances: head shot, head-and-shoulders, full body. + +## Quality + +- Sharp, in-focus. +- Resolution ≥ 1024×1024 ideal. +- JPEG or PNG. + +## Avoid + +- Group photos. +- Heavy makeup not normally worn. +- Costumes / cosplay. +- Hats covering the face. +- Same pose repeated. diff --git a/skills/.curated/higgsfield-soul-id/references/troubleshooting.md b/skills/.curated/higgsfield-soul-id/references/troubleshooting.md new file mode 100644 index 00000000..73fc6945 --- /dev/null +++ b/skills/.curated/higgsfield-soul-id/references/troubleshooting.md @@ -0,0 +1,25 @@ +# Soul Character Troubleshooting + +## Auth Or Plan + +- Auth failure → ask the user to connect/authenticate the Higgsfield MCP server. +- Plan/upgrade error → explain that Soul training requires a paid plan. + +## Photo Quality + +Training may fail when photos are blurry, too dark, heavily filtered, duplicated, or show different people. + +Ask for: + +- 5–20 photos of the same person. +- Clear face visibility. +- Varied angles and lighting. +- Minimal sunglasses, masks, heavy filters, or extreme crops. + +## Uploads + +Local files must go through `media_upload` and `media_confirm`. Pass confirmed media IDs to `show_characters`, not local paths. + +## Long Training + +Use `show_characters` with `action: "status"` or `action: "list"` to check progress. If training stays pending for a long time, report the returned request id if present.