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:
bashbin/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 ascustom.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 asAuthorization: Bearer <key>.
Operating Rules
- 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).
- Confirm with Michael before every
generate, stating the model and expected duration/cost. - Poll
statusno faster than every ~5 seconds. - Output MP4 URLs are temporary. Download promptly; never store the URL as the artifact.
- 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.


