moai-media| Live catalog-based image generation (core:media-higgsfield-core)
Overview
This is a skill that calls the image generation tool of Higgsfield MCP. It extracts intent from the user's natural-language request, narrows down candidates using the family craft, and then parameters are queried from the live catalogand generates. The hardcoded model tables and parameter tables that the previous skill had have been removed — those tables diverged from the live schema and produced failing calls.
The core design is in the core skill media-higgsfield-core:
- Call contract:
../media-higgsfield-core/references/call-schema.md - Live query protocol:
../media-higgsfield-core/references/catalog-protocol.md - Common rules R1–R5:
../media-higgsfield-core/references/universal-rules.md - Job, cost, leadback:
../media-higgsfield-core/references/job-lifecycle.md
Trigger keywords
Higgsfield image, Soul, Nano Banana, Nano Banana Pro, GPT Image, Seedream, FLUX, Recraft, Marketing Studio, DTC ad image, AI image generation, cinematic image, character consistency
Family craft (references/prompt-craft/)
Each file is based on official vendor documentation and cites sources and Evidence tier. It does not deal with parameters, but only with prompt craft.
| File | Family |
|---|---|
references/prompt-craft/soul.md |
Soul (no official prompt formula → R1–R5 fallback) |
references/prompt-craft/nano-banana.md |
Nano Banana (Google 5-part formula) |
references/prompt-craft/openai.md |
GPT Image (openai_hazel mapping is unverified) |
references/prompt-craft/seedream.md |
Seedream (ByteDance 5 principles) |
references/prompt-craft/flux.md |
FLUX (word order is load-bearing, no negative prompts) |
references/prompt-craft/recraft.md |
Recraft (global-to-local, vector/logo) |
references/prompt-craft/marketing-studio.md |
Marketing Studio / DTC Ads (style selection workflow) |
Workflow (REQ-010 flow)
Step 1 — Identify intent → narrow down candidates
Collect slots such as subject, purpose, tone, and literal text from the user request (→ core interview-schema.md), and use the family craft to narrow down candidate models. This step only narrows down candidates and does not assert parameters. If slots are insufficient, the skill returns a blocker report, and the orchestrator confirms with the user (the skill does not ask the user directly).
Candidate narrowing hints (family selection hints, not parameters):
| User expression | Candidate family |
|---|---|
| "exact text", "poster", "card news" | GPT Image or Nano Banana Pro |
| "cinematic", "person detail", "character consistency" | Soul |
| "like a photo", "realistic", "product shot" | FLUX |
| "artistic", "unique tone" | Seedream |
| "logo", "icon", "vector" | Recraft |
| "DTC ad", "product ad format" | Marketing Studio (ms_image) |
Step 2 — Live lookup (models_explore)
models_explore(action:'get')the candidate models narrowed down by actual constraints(aspect_ratios, per-model parameters, media role) are looked up. If the model is out of scope (e.g., z_image, grok_image), state that there is no family craft and live lookupfetch only the constraints with and apply R1–R5. If it is a Marketing Studio family, show_marketing_studiofetch the style list with.
Step 3 — Cost preflight (get_cost)
with the same parameters, put in get_cost: trueand creditscheck (0 credits consumed). If the response has adjustments, it is a default filled in by the server, so note it for readback. The balance stop rule is core job-lifecycle.md.
Step 4 — Approval gate (before credits are spent)
get_costonly looks up the cost with lookupand does not obtain approval. It is the last stop line before credits actually go out, and it follows core §paid generation approval gate as is — show the full prompt, model id, input media, confirmed options, generation count,adjustments, estimated credits, and balance, and obtain approval.
- [HARD] The
adjustmentsobtained in Step 3 is shown here. Step 6 readback is after the money has already gone out — you need to know that the server changed the request while it can still be canceled. - This skill does not ask the user directly, so when it reaches the gate, it returns it as a blocker and the orchestrator asks with
AskUserQuestion.
Step 5 — Generation (generate_image)
call the actual generate_imageonly with approved values. The namespace is resolved at runtime (→ core call-schema.md). Reference images are passed only as media_id/job_id(URLs rejected).
- [HARD] Even if it fails, do not create a new job. If it fails ambiguously, first check the returned job ID with
job_status, and if there is not even an ID, first check whether the generation history lookup tool is actually exposed — all that is in the core contract isjob_status·job_display. If it is not there, ask the user to check the Higgsfield dashboard. Call it again only after it is confirmed to be absent.
Step 6 — Polling and readback
job_status로 completedpoll until, and report the adjustmentsreturned along with the result URL to the user — if the server substituted anything differently from the request, do not hide it.
Marketing Studio (ms_image) hard rules
ms_image는 style_idhas no default, so it is an error without a style. Be sure to show_marketing_studioshow the style list with and have the user choose by name before generating. Do not fill in the style with an automatic default (→ references/prompt-craft/marketing-studio.md).
Out-of-scope model fallback (live lookup)
If a model not in the 15 craft families is requested, state that there is no family-specific craft and models_explorethe constraints with live lookupAfter that, apply the common rules R1–R5. Not having a family file does not mean the model cannot be used, but inform the user of that fact.
Output format
## Higgsfield 이미지 생성 결과
- 모델: [models_explore로 확인한 실제 id]
- 프롬프트: [계열 크래프트로 조립된 최종 프롬프트]
- 비율: [라이브 aspect_ratios 중 선택]
- 비용: [get_cost가 반환한 credits]
- Job ID / 결과 URL: [job_status completed]
- 서버 조정(adjustments): [있으면 그대로 보고]
Precautions
- Prompts follow the vendor official conventions of the family craft (references/prompt-craft/).
- Excluded expressions as positive scene descriptions (R1). Literal text with quotes + font (R3).
- Do not guess the model id or parameters — always
models_exploreconfirm with. - Do not generate content that may infringe on NSFW, portrait rights, or copyright.
Related skills
| Skill | Viewpoint |
|---|---|
moai-media:media-higgsfield-core |
Core: invocation contract, live lookup, common rules |
moai-media:media-higgsfield-video |
Follow-up: image to video |
moai-media:media-gemini-3-image-prompt |
Alternative: produce prompt only (external tool) |
moai-media:media-gpt-image-2-prompt |
Alternative: use external ChatGPT |
moai-marketer:content-card-news |
Follow-up: place image in card news |
Source
- Higgsfield Skills (official agent documentation)
- Higgsfield MCP
- For the prompt craft sources by family, refer to each
references/prompt-craft/*.md's Evidence tier and source references. - Live catalog: runtime
models_explore(the snapshot is only an evidence baseline for the plan stage, not a runtime contract).