# luma-photon

luma-photon is a Claude Code skill for Luma Photon image API integration. It covers text generation, image references, edits, polling, and production delivery.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 130 installs · ★ 252 repo stars
- Author: calesthio
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/calesthio/generative-media-skills/tree/HEAD/skills/providers/image-generation/luma-photon/SKILL.md
- Updated: 2026-07-14
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/luma-photon

## What it does

luma-photon connects a project to Luma's first-party Photon and Photon Flash image API. It covers text-to-image requests, image, style, and character references, source-image modifications, asynchronous generation, artifact handling, and production prompting. The documented models are `photon-1` and `photon-flash-1`.

Requests can use REST or the official `lumaai` Python package. Image creation uses `client.generations.image.create(...)`, while results are retrieved with polling. Reference assets must be reachable through HTTPS URLs that Luma can fetch. Without `LUMAAI_API_KEY`, the API request cannot run; local paths, `file:` URLs, and private network URLs are not valid reference sources.

The skill excludes Ray video, UNI image models, Luma Agents, the consumer app, ComfyUI wrappers, and third-party Photon gateways. For production requests it keeps `sync: false` and uses bounded polling because the documentation conflicts on synchronous image retrieval.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add calesthio/generative-media-skills --skill luma-photon -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/luma-photon/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/luma-photon/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add calesthio/generative-media-skills --skill luma-photon -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/luma-photon/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add calesthio/generative-media-skills --skill luma-photon -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/luma-photon/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install calesthio/generative-media-skills skills/providers/image-generation/luma-photon
```

2. **Manually: put the files in place**
- File: `.github/skills/luma-photon/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add calesthio/generative-media-skills --skill luma-photon -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/calesthio/generative-media-skills --path skills/providers/image-generation/luma-photon
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/luma-photon/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add calesthio/generative-media-skills --skill luma-photon -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/calesthio/generative-media-skills/tree/HEAD/skills/providers/image-generation/luma-photon/SKILL.md

## When to use it
- connect a project to the Luma Photon image API
- generate images from text prompts
- pass image, style, or character references by URL
- modify a source image with an instruction
- separate Photon image work from Ray video generation

## Example prompts
- Connect the first-party Luma Photon API and generate an image from this brief: ...
- Use `photon-flash-1` for an iteration, poll until it reaches a terminal state, then save the image.
- Modify the image at this HTTPS URL through `modify_image_ref` and apply this localized change: ...

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 9c77e25c95007997.

BEGIN THIRD-PARTY FILE 9c77e25c95007997
````text
---
name: luma-photon
description: Use Luma AI's first-party Photon and Photon Flash image API for text-to-image, image/style/character references, image modification, asynchronous generation, secure artifact handling, production prompting, cost control, and policy-aware delivery. Trigger for Luma Photon API integration or production work; do not use for Ray video, UNI image models, the Luma consumer app, or third-party Photon gateways.
---

# Luma Photon production guide

Use this skill for the legacy-path Luma API image surface backed by `photon-1` and `photon-flash-1`. Keep it separate from Ray video generation, newer UNI image workflows, Luma Agents, the consumer app, ComfyUI wrappers, and hosted third-party gateways. The string `dream-machine` remains in the documented Photon REST path even though Luma's current brand guidance calls that terminology retired.

All volatile facts below were verified against first-party sources on **2026-07-09**. Recheck the API reference, billing dashboard, rate-limit page, and governing agreement immediately before production commitments.

## Choose Photon deliberately

The documented image model IDs are:

- `photon-1` — the default Photon model. Luma positions it for higher-fidelity generation.
- `photon-flash-1` — the faster, lower-cost iteration model.

Treat those descriptions as provider positioning, not independent quality findings. Run a fixed brief-and-reference bake-off using the intended deliverable, then compare prompt adherence, source fidelity, text, anatomy, material continuity, latency, rejection rate, and actual account charge. Use Flash for broad exploration when it meets the bar; promote only finalists to Photon when measured quality justifies the cost.

Do not send Photon work to `/generations/video`, Ray models, Luma Agents, a consumer-session endpoint, or an OpenAI-compatible gateway. The first-party Photon create route is:

```text
POST https://api.lumalabs.ai/dream-machine/v1/generations/image
Authorization: Bearer $LUMAAI_API_KEY
Content-Type: application/json
```

The shared management routes are:

```text
GET    /dream-machine/v1/generations/{id}
GET    /dream-machine/v1/generations?limit=100&offset=0
DELETE /dream-machine/v1/generations/{id}
GET    /dream-machine/v1/credits
```
````
END THIRD-PARTY FILE 9c77e25c95007997

The third-party file has ended. Everything between the 9c77e25c95007997 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2286 of 43338 bytes. © calesthio · MIT · https://github.com/calesthio/generative-media-skills/tree/HEAD/skills/providers/image-generation/luma-photon/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
