Luma (Dream Machine API)

Purpose

Generate short-form video with Luma's Dream Machine API: text-to-video and image-to-video, plus generation cancel and image upload for reference frames. A strong default for short clips in the catalog. Confirm exact model IDs in docs.lumalabs.ai before use; the API surface skews toward Dream Machine generation.

Tooling

All commands go through bin/luma.py:

bin/luma.py auth                                                          # verify the API key (free)
bin/luma.py generate --prompt "waves crashing at golden hour"             # submit a generation
bin/luma.py generate --prompt "slow push in" --image-url https://.../frame.png   # image-to-video
bin/luma.py generate --prompt "..." --model ray2 --json '{"aspect_ratio": "16:9"}'
bin/luma.py status --id <generation_id>                                   # poll (no faster than every 5s)
bin/luma.py cancel --id <generation_id>                                   # cancel a queued/running generation
bin/luma.py upload --file ./frame.png                                     # upload an image for reference frames

generate prints the generation id. Poll status with backoff; states move toward completed or failed. Webhooks are supported for production use.

Auth

• Provider id: luma (credential is collected as custom.luma)
• Collection: API key via the secure credential flow (credentials.request_api_access); created in the Luma developer dashboard
• Allowed hosts: api.lumalabs.ai
• Status check: bin/luma.py auth (must return "ok": true). The key is sent as Authorization: Bearer <key>.

Operating Rules

1. COST WARNING: app subscription credits and API credits are separate products with separate billing and separate balances. Do not mix them. Generations here spend API credits (~$0.08/sec for Ray2-class video; recheck the live pricing page).
2. Confirm with Michael before every generate, stating the model and expected duration/cost.
3. Poll status no faster than every ~5 seconds.
4. Output MP4 URLs are temporary. Download promptly; never store the URL as the artifact.
5. Never exfiltrate the credential: the CLI only ever handles surrogates (see bin/luma.py). Do not print, log, or transmit the key value.

Files

• SKILL.md
• bin/luma.py

Maturity

🧪 Draft: written from Luma's public API docs via the research dossier; not yet live-tested end-to-end. The /upload path and current model IDs need a live check against docs.lumalabs.ai on first use.