Magic Light AI — Intelligent Lighting Design and Atmosphere Generator for Any Scene

## Getting Started

> Send me a scene description, mood reference, or environment type and I'll generate a complete lighting setup instantly. No idea yet? Just describe the feeling you want to create.

**Try saying:**
- "I'm shooting a moody indoor portrait in a small apartment at night — suggest a cinematic lighting setup using minimal gear"
- "Design a warm, cozy lighting scheme for a living room interior render with a late afternoon autumn feel"
- "I'm planning a short film scene in an abandoned warehouse — give me a dramatic, high-contrast lighting plan with shadow play"

### Quick Start Setup

This skill connects to a cloud processing backend. On first use, set up the connection automatically and let the user know ("Connecting...").

**Token check**: Look for `NEMO_TOKEN` in the environment. If found, skip to session creation. Otherwise:
- Generate a UUID as client identifier
- POST `https://mega-api-prod.nemovideo.ai/api/auth/anonymous-token` with `X-Client-Id` header
- Extract `data.token` from the response — this is your NEMO_TOKEN (100 free credits, 7-day expiry)

**Session**: POST `https://mega-api-prod.nemovideo.ai/api/tasks/me/with-session/nemo_agent` with Bearer auth and body `{"task_name":"project"}`. Keep the returned `session_id` for all operations.

Let the user know with a brief "Ready!" when setup is complete. Don't expose tokens or raw API output.

# Light Your World Without the Guesswork

Getting lighting right is one of the hardest creative challenges — whether you're staging a photoshoot, setting up a 3D scene, designing an interior mood board, or planning a film sequence. Too warm, too harsh, wrong angle, wrong color temperature — and the whole atmosphere falls apart. magic-light-ai was built to eliminate that frustration entirely.

This skill acts as your personal lighting director. Describe the mood you're after, the environment you're working in, or the emotional tone you want to convey, and magic-light-ai generates a complete lighting recommendation tailored to your exact situation. From golden-hour outdoor portraits to dramatic noir interiors, it covers the full spectrum of creative lighting needs.

Whether you're a solo photographer working on location, a 3D artist setting up render environments, or a production designer planning a scene, magic-light-ai gives you a confident starting point — and the flexibility to refine from there. Stop guessing and start creating with intention.

## Routing Your Light Requests

Every prompt you send — whether you're describing a golden-hour interior, a moody cinematic setup, or a festival stage wash — gets parsed for scene type, mood keywords, and fixture intent before being dispatched to the appropriate Magic Light AI lighting engine.

| User says... | Action | Skip SSE? |
|-------------|--------|----------|
| "export" / "导出" / "download" / "send me the video" | → §3.5 Export | ✅ |
| "credits" / "积分" / "balance" / "余额" | → §3.3 Credits | ✅ |
| "status" / "状态" / "show tracks" | → §3.4 State | ✅ |
| "upload" / "上传" / user sends file | → §3.2 Upload | ✅ |
| Everything else (generate, edit, add BGM…) | → §3.1 SSE | ❌ |

## Cloud Rendering API Reference

Magic Light AI processes all lighting calculations through a cloud-based photon simulation backend, meaning complex bounce light, color temperature blending, and atmospheric haze rendering happen server-side without taxing your local device. Each API call carries your scene context, fixture parameters, and render quality tier so the backend returns a fully resolved lighting blueprint.

Skill attribution — read from this file's YAML frontmatter at runtime:
- `X-Skill-Source`: `magic-light-ai`
- `X-Skill-Version`: from frontmatter `version`
- `X-Skill-Platform`: detect from install path (`~/.clawhub/` → `clawhub`, `~/.cursor/skills/` → `cursor`, else `unknown`)

**All requests** must include: `Authorization: Bearer <NEMO_TOKEN>`, `X-Skill-Source`, `X-Skill-Version`, `X-Skill-Platform`. Missing attribution headers will cause export to fail with 402.

**API base**: `https://mega-api-prod.nemovideo.ai`

**Create session**: POST `/api/tasks/me/with-session/nemo_agent` — body `{"task_name":"project","language":"<lang>"}` — returns `task_id`, `session_id`.

**Send message (SSE)**: POST `/run_sse` — body `{"app_name":"nemo_agent","user_id":"me","session_id":"<sid>","new_message":{"parts":[{"text":"<msg>"}]}}` with `Accept: text/event-stream`. Max timeout: 15 minutes.

**Upload**: POST `/api/upload-video/nemo_agent/me/<sid>` — file: multipart `-F "files=@/path"`, or URL: `{"urls":["<url>"],"source_type":"url"}`

**Credits**: GET `/api/credits/balance/simple` — returns `available`, `frozen`, `total`

**Session state**: GET `/api/state/nemo_agent/me/<sid>/latest` — key fields: `data.state.draft`, `data.state.video_infos`, `data.state.generated_media`

**Export** (free, no credits): POST `/api/render/proxy/lambda` — body `{"id":"render_<ts>","sessionId":"<sid>","draft":<json>,"output":{"format":"mp4","quality":"high"}}`. Poll GET `/api/render/proxy/lambda/<id>` every 30s until `status` = `completed`. Download URL at `output.url`.

Supported formats: mp4, mov, avi, webm, mkv, jpg, png, gif, webp, mp3, wav, m4a, aac.

### SSE Event Handling

| Event | Action |
|-------|--------|
| Text response | Apply GUI translation (§4), present to user |
| Tool call/result | Process internally, don't forward |
| `heartbeat` / empty `data:` | Keep waiting. Every 2 min: "⏳ Still working..." |
| Stream closes | Process final response |

~30% of editing operations return no text in the SSE stream. When this happens: poll session state to verify the edit was applied, then summarize changes to the user.

### Backend Response Translation

The backend assumes a GUI exists. Translate these into API actions:

| Backend says | You do |
|-------------|--------|
| "click [button]" / "点击" | Execute via API |
| "open [panel]" / "打开" | Query session state |
| "drag/drop" / "拖拽" | Send edit via SSE |
| "preview in timeline" | Show track summary |
| "Export button" / "导出" | Execute export workflow |

**Draft field mapping**: `t`=tracks, `tt`=track type (0=video, 1=audio, 7=text), `sg`=segments, `d`=duration(ms), `m`=metadata.

```
Timeline (3 tracks): 1. Video: city timelapse (0-10s) 2. BGM: Lo-fi (0-10s, 35%) 3. Title: "Urban Dreams" (0-3s)
```

### Error Handling

| Code | Meaning | Action |
|------|---------|--------|
| 0 | Success | Continue |
| 1001 | Bad/expired token | Re-auth via anonymous-token (tokens expire after 7 days) |
| 1002 | Session not found | New session §3.0 |
| 2001 | No credits | Anonymous: show registration URL with `?bind=<id>` (get `<id>` from create-session or state response when needed). Registered: "Top up credits in your account" |
| 4001 | Unsupported file | Show supported formats |
| 4002 | File too large | Suggest compress/trim |
| 400 | Missing X-Client-Id | Generate Client-Id and retry (see §1) |
| 402 | Free plan export blocked | Subscription tier issue, NOT credits. "Register or upgrade your plan to unlock export." |
| 429 | Rate limit (1 token/client/7 days) | Retry in 30s once |

## Common Workflows

magic-light-ai fits naturally into a wide range of creative pipelines. For photographers, the most common workflow is describing a shoot location and subject, then receiving a recommended light placement diagram, color temperature range, and modifier suggestions — all before arriving on set.

For 3D artists and render designers, the skill excels at translating mood references into specific HDRI suggestions, key/fill/rim ratios, and color grading starting points that match the desired atmosphere. Describe your scene in plain language and get render-ready lighting logic back.

Interior designers use magic-light-ai to prototype lighting schemes for client presentations — inputting room dimensions, wall colors, and intended use (e.g., home office vs. relaxation lounge) to receive layered lighting plans that balance ambient, task, and accent sources. It's equally useful for film and theater pre-production, where lighting cues can be drafted from script descriptions alone.

## FAQ

**Can magic-light-ai work for both natural and artificial lighting setups?** Yes — it handles both with equal depth. Whether you're working with sunlight, studio strobes, practical lamps, or virtual render lights, the skill adapts its recommendations to your specific light sources.

**Does it work for video game environment lighting?** Absolutely. Describe your game's art style, time of day, and emotional tone and magic-light-ai will suggest directional light angles, ambient occlusion intensity, and color palette guidance suitable for real-time environments.

**Can I use it without any lighting knowledge?** That's exactly what it's designed for. Beginners can describe a scene in plain conversational language and receive step-by-step guidance. Experienced professionals can use technical terminology for more granular output.

**What if I don't like the first suggestion?** Just ask for a revision — specify what feels off (too flat, too cold, too theatrical) and magic-light-ai will recalibrate and offer an adjusted recommendation.

## Tips and Tricks

The more specific your scene description, the more precise and useful the output from magic-light-ai will be. Instead of saying 'a dark room,' try 'a narrow hallway at midnight with one practical lamp on the far wall' — that level of detail unlocks much richer recommendations.

Use emotional language freely. magic-light-ai is trained to interpret tone words like 'melancholic,' 'electric,' 'intimate,' or 'clinical' and translate them into concrete lighting parameters. Don't be afraid to mix references — 'like a Vermeer painting but in a modern kitchen' is a completely valid prompt.

If you're iterating on a concept, ask for variations explicitly. Request a 'warmer version,' a 'more dramatic contrast option,' or a 'budget-friendly alternative' and the skill will adapt its recommendations accordingly. You can also ask magic-light-ai to explain the reasoning behind each suggestion, which is especially useful for learning and client communication.