Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Luma AI

Scalekit connector
Open markdown

The Luma AI connector lets your AI agent act in each user's Luma AI account. Each user connects their own Luma AI access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 14 tools.

Tools
14
What they doRead · write · destructive
5 · 8 · 15 read8 write1 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Luma AI connection

    In AgentKit > Connections, create a Luma AI connection. The name you give it is the connection_name your code passes. See Configure connections.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'lumalabs'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Luma AI:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'lumalabs_get_credits',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their Luma AI credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • lumalabs_get_creditsGet the remaining credit balance of the Luma AI account behind this API key.Read-only

    Get Credits

    Get the remaining credit balance of the Luma AI account behind this API key. Returns credit_balance, in US cents. Use this to check the account can pay for a generation before starting one.

    Inputs

    This tool takes no inputs.

  • lumalabs_get_generationGet one Luma AI generation (video, image, upscale, audio, modify or reframe job) by its ID.Read-only

    Get Generation

    Get one Luma AI generation (video, image, upscale, audio, modify or reframe job) by its ID. Returns id, generation_type, state (queued, dreaming, completed or failed), failure_reason, created_at, model, the original request, and assets with the video, image or progress_video URL. Use this to poll a job you just started until it is completed or failed. Use lumalabs_list_generations to browse past generations.

    Inputs

    generation_idstringrequired
    ID (UUID) of a Luma AI generation, as returned by a create tool or lumalabs_list_generations. Example: 123e4567-e89b-12d3-a456-426614174000
  • lumalabs_list_camera_motionsList the camera motion phrases Luma AI recognizes in video prompts, such as "camera orbit left".Read-only

    List Camera Motions

    List the camera motion phrases Luma AI recognizes in video prompts, such as "camera orbit left". Returns an array of camera motion strings (wrapped as array in the tool result). Use this to find wording for camera moves inside a prompt. Use lumalabs_list_concepts for structured concept keys, which Luma now recommends.

    Inputs

    This tool takes no inputs.

  • lumalabs_list_conceptsList the camera concept keys Luma AI Ray accepts, such as dolly_zoom, orbit_left, push_in and aerial_drone.Read-only

    List Concepts

    List the camera concept keys Luma AI Ray accepts, such as dolly_zoom, orbit_left, push_in and aerial_drone. Returns an array of concept key strings (wrapped as array in the tool result). Use this to pick values for the concepts input of lumalabs_create_video or lumalabs_extend_video. Use lumalabs_list_camera_motions for camera phrases to write into a prompt instead.

    Inputs

    This tool takes no inputs.

  • lumalabs_list_generationsList the Luma AI generations made with this API key, newest first, one page at a time.Read-only

    List Generations

    List the Luma AI generations made with this API key, newest first, one page at a time. Returns generations (each with id, state, assets, model and request), plus count, limit, offset and has_more. Use this to browse or find past generations. Use lumalabs_get_generation when you already have an ID.

    Inputs

    limitinteger
    Maximum number of generations to return in this page. Server default is 100. Example: 20
    offsetinteger
    Number of generations to skip, for paging. Use the previous offset plus limit while has_more is true. Server default is 0. Example: 20
  • lumalabs_add_audioGenerate a soundtrack and sound effects for a completed Luma AI video generation from a text prompt.Write

    Add Audio

    Generate a soundtrack and sound effects for a completed Luma AI video generation from a text prompt. Returns a generation object for the audio job; the video with audio appears in its assets.video once state is completed. Use this to add sound to a video made with Luma AI. The source must be a completed video generation. Poll lumalabs_get_generation with the returned id until state is completed or failed.

    Inputs

    generation_idstringrequired
    ID (UUID) of a Luma AI generation, as returned by a create tool or lumalabs_list_generations. It must be a completed video generation. Example: 123e4567-e89b-12d3-a456-426614174000
    promptstringrequired
    Text describing the audio to generate. Example: Crunching snow footsteps and a distant wind howl
    negative_promptstring
    Sounds to avoid in the generated audio. Example: music, speech
  • lumalabs_create_imageGenerate an image with Luma AI's Photon models from a text prompt, optionally guided by reference images, a style image, a character's photos, or an image to edit.Write

    Create Image

    Generate an image with Luma AI's Photon models from a text prompt, optionally guided by reference images, a style image, a character's photos, or an image to edit. Returns the generation object with its id and state; the image URL appears in assets.image once state is completed (set sync to true to wait for it in the same call). Use this for still images and image edits. Use lumalabs_reframe_image to change an existing image's aspect ratio, and lumalabs_create_video for video.

    Inputs

    promptstringrequired
    Text describing the image to generate, or the change to make when modify_image_url is set. Example: A teddy bear in sunglasses playing electric guitar
    aspect_ratiostring
    Aspect ratio of the output: one of 1:1, 16:9, 9:16, 4:3, 3:4, 21:9 or 9:21. Example: 9:16 Leave empty for the server default (16:9).one of 1:116:99:164:33:421:99:21
    character_ref_imagesarray
    Up to 4 public photo URLs of the same person, used to keep that character consistent in the image. More photos give a better likeness. Example: ["https://example.com/person-1.jpg"]
    formatstring
    Output file format: jpg or png. Leave empty for jpg. Example: pngone of jpgpng
    image_refarray
    Up to 4 reference images that guide the content of the generation, each with a public url and an optional weight from 0 to 1 that sets its influence. Useful for variations of an image or hard-to-describe concepts. Example: [{"url": "https://example.com/ref.jpg", "weight": 0.85}]
    modelstring
    Photon image model: photon-1 (higher quality) or photon-flash-1 (faster and cheaper). Defaults to photon-1. Example: photon-flash-1one of photon-1photon-flash-1default photon-1
    modify_image_urlstring
    Public URL of an existing image to edit according to the prompt (image-to-image). Example: https://example.com/garden.jpg
    modify_image_weightnumber
    How closely the result follows modify_image_url, from 0 to 1: higher stays closer to the input, lower is more creative. For color changes Luma recommends 0.0 to 0.1. Only used with modify_image_url. Example: 0.8
    style_refarray
    Style reference images whose look is applied to the generation, each with a public url and an optional weight from 0 to 1. Example: [{"url": "https://example.com/style.jpg", "weight": 0.8}]
    syncboolean
    Set to true to wait for the image to finish and return the completed generation in this call, instead of polling lumalabs_get_generation. Example: true
    sync_timeoutnumber
    Seconds to wait when sync is true (server default 60; capped at 100 by this tool). If the image is not done in time, poll lumalabs_get_generation. Example: 60
  • lumalabs_create_videoStart a Luma AI Ray video generation from a text prompt, optionally guided by a start and/or end image and camera concepts.Write

    Create Video

    Start a Luma AI Ray video generation from a text prompt, optionally guided by a start and/or end image and camera concepts. Returns the new generation object with its id and state (queued); the video URL appears in assets.video once state is completed. Use this for text-to-video and image-to-video. Use lumalabs_extend_video to continue or bridge an existing generated video, and lumalabs_create_image for still images. Poll lumalabs_get_generation with the returned id until state is completed or failed.

    Inputs

    promptstringrequired
    Text describing the video: subject, action, setting and style (3 to 5000 characters). Camera moves can also be written in the prompt, for example 'camera orbit left'. Example: A tiger walking through fresh snow at dawn, cinematic
    aspect_ratiostring
    Aspect ratio of the output: one of 1:1, 16:9, 9:16, 4:3, 3:4, 21:9 or 9:21. Example: 9:16 Leave empty for the server default (16:9).one of 1:116:99:164:33:421:99:21
    conceptsarray
    Camera concept keys that steer camera movement and framing, combined in one shot. Get valid keys from lumalabs_list_concepts; common ones are dolly_zoom, orbit_left, push_in, aerial_drone and handheld. Example: ["dolly_zoom", "handheld"]
    durationstring
    Video length: 5s or 9s. Leave empty for the default (5s). Example: 5sone of 5s9s
    end_image_urlstring
    Public URL of an image to use as the last frame; the video animates toward it. Can be combined with start_image_url to animate between two images. Example: https://example.com/end-frame.jpg
    loopboolean
    Set to true to make the video loop seamlessly (last frame flows into the first). Not supported when both a start and an end image are given. Example: true
    modelstring
    Ray video model to use: ray-2 (higher quality) or ray-flash-2 (faster and cheaper). Defaults to ray-2. Example: ray-flash-2one of ray-2ray-flash-2default ray-2
    resolutionstring
    Output resolution: 540p, 720p, 1080p or 4k. Higher resolutions cost more. Leave empty for the model default. Example: 720pone of 540p720p1080p4k
    start_image_urlstring
    Public URL of an image to use as the first frame (image-to-video). Must be reachable by Luma's servers; upload it to your own storage or CDN first. Example: https://example.com/start-frame.jpg
All 148 in AI