Luma Image Generation Skill
Generates images using the Luma AI Photon model (Dream Machine API). Handles API key detection, interactive prompt collection, parameter selection, async polling, and final image download — all via the bundled scripts/luma_imagegen.py CLI.
When to use
- Generate a new image from a text description using Luma AI (Photon / Photon Flash)
- Use a reference image to guide style, structure, or character consistency
- Modify or stylize an existing image using Luma's
modify_image_ref
Workflow
- Check API key — detect
LUMA_API_KEYin environment. If missing, guide the user (see below). - Collect inputs — ask the user for: prompt, aspect ratio, model choice, and any optional reference images.
- Build the structured prompt — augment the user's description into a labeled spec (see prompt template below).
- Run the bundled CLI — execute
scripts/luma_imagegen.pywith the collected parameters. - Poll until complete — the script handles async polling automatically; wait for
state: completed. - Display result — show the final image URL and download the image to
output/luma/. - Iterate — if the result doesn't match expectations, adjust the prompt and re-run.
API key detection & setup
Before any API call, check for the key:
python3 ${CLAUDE_SKILL_DIR}/scripts/luma_imagegen.py --check-keyIf LUMA_API_KEY is missing:
- Tell the user the key is not set.
- Direct them to generate one: https://lumalabs.ai/dream-machine/api/keys
- Ask them to add it to their
.envfile or export it in their shell:bashexport LUMA_API_KEY=your_key_here - Never ask the user to paste the key in chat. Ask them to set it locally and confirm when ready.
- Once confirmed, retry the
--check-keycommand to verify.
Interactive questions to ask the user
Ask these questions before running the generation:
- Prompt (required): "What image do you want to generate? Describe the scene, subject, style, and any important details."
- Aspect ratio (optional, default
16:9): "What aspect ratio? Options:1:1,3:4,4:3,9:16,16:9(default),9:21,21:9" - Model (optional, default
photon-1): "Usephoton-1(higher quality) orphoton-flash-1(faster and cheaper)?" - Reference image (optional): "Do you have a reference image URL for style or structure guidance?"
Only ask what's needed — skip questions the user has already answered in their message.
Running the CLI
python3 ${CLAUDE_SKILL_DIR}/scripts/luma_imagegen.py \
--prompt "YOUR AUGMENTED PROMPT" \
--aspect-ratio 16:9 \
--model photon-1 \
[--image-ref "https://example.com/ref.jpg" --image-ref-weight 0.85] \
[--out output/luma/]All flags:
| Flag | Default | Description |
|---|---|---|
--prompt |
(required) | Text description of the image |
--aspect-ratio |
16:9 |
1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9 |
--model |
photon-1 |
photon-1 or photon-flash-1 |
--image-ref |
— | Public URL for style/structure reference |
--image-ref-weight |
0.85 |
Weight of reference image (0.0–1.0) |
--modify-ref |
— | Base image URL to modify |
--modify-ref-weight |
0.5 |
Weight for modification fidelity |
--out |
output/luma/ |
Output directory for downloaded images |
--poll-interval |
3 |
Seconds between polling requests |
--check-key |
— | Verify LUMA_API_KEY is set and exit |
Output conventions
- Save final images to
output/luma/with descriptive filenames (e.g.,photon1_hero_16x9.png). The output directory is relative to the current working directory when the script is invoked. - Log the generation ID for reference (useful to retrieve the image later).
- If the generation fails, show the
failure_reasonfrom the API response.
Prompt augmentation
Reformat the user's description into a structured spec. Only make implied details explicit — do not invent new requirements.
Template (include only relevant lines):
Primary request: <user's main prompt>
Scene/background: <environment or setting>
Subject: <main subject>
Style/medium: <photo/illustration/3D/cinematic/etc>
Composition/framing: <wide/close-up/overhead; subject placement>
Lighting/mood: <lighting type and emotional tone>
Color palette: <dominant colors or palette notes>
Aspect ratio: <e.g., 16:9 landscape>
Avoid: <elements to exclude>Augmentation rules:
- Keep it concise — add only what the user implied or provided.
- Always include "Avoid:" to prevent common quality issues (watermarks, logos, blur).
- For modification requests, explicitly list what should change and what must stay the same.
Example augmented prompts
Landscape hero image
Primary request: a misty mountain lake at sunrise
Scene/background: alpine lake surrounded by pine trees, light morning fog
Style/medium: photorealistic nature photography
Composition/framing: wide panoramic, lake centered, mountains in background
Lighting/mood: golden hour, warm and serene
Aspect ratio: 16:9 landscape
Avoid: people, boats, watermarks, oversaturationProduct shot
Primary request: a ceramic coffee mug on a wooden table
Scene/background: warm kitchen interior, soft bokeh background
Subject: minimalist white ceramic mug, steam rising
Style/medium: clean product photography
Lighting/mood: soft diffused window light
Aspect ratio: 1:1 square
Avoid: text, logos, harsh shadows, clutterPrompting best practices
- Describe scene → subject → style → composition → lighting.
- Mention the intended use (hero image, social post, product shot) to calibrate detail level.
- Use "Avoid:" to eliminate common defects (watermarks, blur, stock-photo clichés).
- For modifications, list invariants explicitly ("change only the background; keep the mug unchanged").
- Start with
photon-flash-1for quick iteration; switch tophoton-1for final quality. - If the result isn't satisfactory, make one targeted change per iteration.
Models reference
| Model | Speed | Quality | Best for |
|---|---|---|---|
photon-1 |
Slower | Higher | Final assets, complex scenes |
photon-flash-1 |
Fast | Good | Rapid iteration, drafts |
Dependencies
The script uses only the Python standard library. No additional packages are required.
Luma Image Generation Skill
Generates images using the Luma AI Photon model (Dream Machine API). Handles API key detection, interactive prompt collection, parameter selection, async polling, and final image download — all via the bundled scripts/luma_imagegen.py CLI.
When to use
- Generate a new image from a text description using Luma AI (Photon / Photon Flash)
- Use a reference image to guide style, structure, or character consistency
- Modify or stylize an existing image using Luma's
modify_image_ref
Workflow
- Check API key — detect
LUMA_API_KEYin environment. If missing, guide the user (see below). - Collect inputs — ask the user for: prompt, aspect ratio, model choice, and any optional reference images.
- Build the structured prompt — augment the user's description into a labeled spec (see prompt template below).
- Run the bundled CLI — execute
scripts/luma_imagegen.pywith the collected parameters. - Poll until complete — the script handles async polling automatically; wait for
state: completed. - Display result — show the final image URL and download the image to
output/luma/. - Iterate — if the result doesn't match expectations, adjust the prompt and re-run.
API key detection & setup
Before any API call, check for the key:
python3 ${CLAUDE_SKILL_DIR}/scripts/luma_imagegen.py --check-keyIf LUMA_API_KEY is missing:
- Tell the user the key is not set.
- Direct them to generate one: https://lumalabs.ai/dream-machine/api/keys
- Ask them to add it to their
.envfile or export it in their shell:bashexport LUMA_API_KEY=your_key_here - Never ask the user to paste the key in chat. Ask them to set it locally and confirm when ready.
- Once confirmed, retry the
--check-keycommand to verify.
Interactive questions to ask the user
Ask these questions before running the generation:
- Prompt (required): "What image do you want to generate? Describe the scene, subject, style, and any important details."
- Aspect ratio (optional, default
16:9): "What aspect ratio? Options:1:1,3:4,4:3,9:16,16:9(default),9:21,21:9" - Model (optional, default
photon-1): "Usephoton-1(higher quality) orphoton-flash-1(faster and cheaper)?" - Reference image (optional): "Do you have a reference image URL for style or structure guidance?"
Only ask what's needed — skip questions the user has already answered in their message.
Running the CLI
python3 ${CLAUDE_SKILL_DIR}/scripts/luma_imagegen.py \
--prompt "YOUR AUGMENTED PROMPT" \
--aspect-ratio 16:9 \
--model photon-1 \
[--image-ref "https://example.com/ref.jpg" --image-ref-weight 0.85] \
[--out output/luma/]All flags:
| Flag | Default | Description |
|---|---|---|
--prompt |
(required) | Text description of the image |
--aspect-ratio |
16:9 |
1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9 |
--model |
photon-1 |
photon-1 or photon-flash-1 |
--image-ref |
— | Public URL for style/structure reference |
--image-ref-weight |
0.85 |
Weight of reference image (0.0–1.0) |
--modify-ref |
— | Base image URL to modify |
--modify-ref-weight |
0.5 |
Weight for modification fidelity |
--out |
output/luma/ |
Output directory for downloaded images |
--poll-interval |
3 |
Seconds between polling requests |
--check-key |
— | Verify LUMA_API_KEY is set and exit |
Output conventions
- Save final images to
output/luma/with descriptive filenames (e.g.,photon1_hero_16x9.png). The output directory is relative to the current working directory when the script is invoked. - Log the generation ID for reference (useful to retrieve the image later).
- If the generation fails, show the
failure_reasonfrom the API response.
Prompt augmentation
Reformat the user's description into a structured spec. Only make implied details explicit — do not invent new requirements.
Template (include only relevant lines):
Primary request: <user's main prompt>
Scene/background: <environment or setting>
Subject: <main subject>
Style/medium: <photo/illustration/3D/cinematic/etc>
Composition/framing: <wide/close-up/overhead; subject placement>
Lighting/mood: <lighting type and emotional tone>
Color palette: <dominant colors or palette notes>
Aspect ratio: <e.g., 16:9 landscape>
Avoid: <elements to exclude>Augmentation rules:
- Keep it concise — add only what the user implied or provided.
- Always include "Avoid:" to prevent common quality issues (watermarks, logos, blur).
- For modification requests, explicitly list what should change and what must stay the same.
Example augmented prompts
Landscape hero image
Primary request: a misty mountain lake at sunrise
Scene/background: alpine lake surrounded by pine trees, light morning fog
Style/medium: photorealistic nature photography
Composition/framing: wide panoramic, lake centered, mountains in background
Lighting/mood: golden hour, warm and serene
Aspect ratio: 16:9 landscape
Avoid: people, boats, watermarks, oversaturationProduct shot
Primary request: a ceramic coffee mug on a wooden table
Scene/background: warm kitchen interior, soft bokeh background
Subject: minimalist white ceramic mug, steam rising
Style/medium: clean product photography
Lighting/mood: soft diffused window light
Aspect ratio: 1:1 square
Avoid: text, logos, harsh shadows, clutterPrompting best practices
- Describe scene → subject → style → composition → lighting.
- Mention the intended use (hero image, social post, product shot) to calibrate detail level.
- Use "Avoid:" to eliminate common defects (watermarks, blur, stock-photo clichés).
- For modifications, list invariants explicitly ("change only the background; keep the mug unchanged").
- Start with
photon-flash-1for quick iteration; switch tophoton-1for final quality. - If the result isn't satisfactory, make one targeted change per iteration.
Models reference
| Model | Speed | Quality | Best for |
|---|---|---|---|
photon-1 |
Slower | Higher | Final assets, complex scenes |
photon-flash-1 |
Fast | Good | Rapid iteration, drafts |
Dependencies
The script uses only the Python standard library. No additional packages are required.
Scanned by
NVIDIA SkillSpector
Automated static analysis (no LLM) · v2.12.0 · 2026-11-19
Partial analysis: some checks could not run on this component.
7 observations in 4 categories
- Privilege Escalation 4
- Data Exfiltration 1
- Excessive Agency 1
- MCP Least Privilege 1
SkillSpector looks for patterns such as shell commands, credential access, network calls or unpinned dependencies. An observation is something worth reading in the files before you install, not a confirmed vulnerability. Components that run code locally, like hooks, MCP servers and security tooling, naturally show more of them. Open one to see the lines it points at.
Credential Access ×4Privilege Escalation · scripts/luma_imagegen.py:32
| 30 | |
| 31 | def get_api_key() -> str: |
| 32 | """Read LUMA_API_KEY from environment or .env file.""" |
| 33 | key = os.environ.get("LUMA_API_KEY") |
| 34 | if key: |
Autonomous Decision MakingExcessive Agency · SKILL.md:41
| 39 | export LUMA_API_KEY=your_key_here |
| 40 | ``` |
| 41 | 4. **Never ask the user to paste the key in chat.** Ask them to set it locally and confirm when ready. |
| 42 | 5. Once confirmed, retry the `--check-key` command to verify. |
| 43 |
Without declared permissions the skill's intent is opaque and cannot be validated.MCP Least Privilege · SKILL.md:1
| 1 | --- |
| 2 | name: "luma-imagegen" |
| 3 | description: "Use when the user asks to generate images via the Luma AI API (Dream Machine / Photon); collects a prompt and options interactively, then calls the API using the bundled script. Requires LUMA_API_KEY — will prompt the user if |
External TransmissionData Exfiltration · scripts/luma_imagegen.py:23
| 21 | |
| 22 | |
| 23 | API_BASE = "https://api.lumalabs.ai/dream-machine/v1" |
| 24 | IMAGE_ENDPOINT = f"{API_BASE}/generations/image" |
| 25 | STATUS_ENDPOINT = f"{API_BASE}/generations/{{generation_id}}" |
Learn more about NVIDIA SkillSpector or how components are reviewed.
Agent compatibility
Checked by NVIDIA SkillEvaluator Harness Check · v1.0.1 · 2026-11-18
How each agent reads this skill once it is installed, from the agents' documented loading rules. No agent was run. A note means the agent loads the skill but changes part of its text, or drops it.
Claude Code
loadsCodex
loads · 1 noteCopilot CLI
loads · 1 noteOpenCode
loads · 1 noteHermes
loads · 1 noteOpenClaw
loads · 1 note
Codex · loads with changes
${CLAUDE_SKILL_DIR} is not substituted: the model sees the literal text.
Fix: Use paths relative to SKILL.md.
CX-SKILL-DIR · verified on 0.166.0
Copilot CLI · loads with changes
${CLAUDE_SKILL_DIR} is not substituted: the model sees the literal text.
Fix: Use paths relative to SKILL.md.
CP-SKILL-DIR · verified on 1.0.105
OpenCode · loads with changes
${CLAUDE_SKILL_DIR} is not substituted: the model sees the literal text.
Fix: Use paths relative to SKILL.md.
OC-SKILL-DIR · verified on 1.19.5
Hermes · loads with changes
${CLAUDE_SKILL_DIR} is not substituted: the model sees the literal text.
Fix: Use ${HERMES_SKILL_DIR} or paths relative to SKILL.md.
HM-SKILL-DIR · verified on main
OpenClaw · loads with changes
${CLAUDE_SKILL_DIR} is not substituted: the model sees the literal text.
Fix: Use paths relative to SKILL.md.
OW-SKILL-DIR · verified on 2026.10.9
Learn more about NVIDIA SkillEvaluator.