luma_capability_describe
ChatGPTOne capability in depth: what it does, the intake fields it expects, and the stages of the document it produces. Call it after luma_capability_list and before luma_session_run_capability.
luma_capability_list
ChatGPTThe capabilities this API key's team may run — slug, name, and what each one does. Empty when none are entitled. Inspect one with luma_capability_describe, and run one with luma_session_run_capability.
luma_generate_image
ChatGPTCreate or edit one still image in a session you already opened. Use it for a hero shot, a product still, a poster frame, a thumbnail, or a variation on an image the workspace already holds (type='image_edit', the asset_id in source — editing never changes the original). Name the model by an image row's id from luma_model_list. A third-party model takes prompt, aspect_ratio, medias and the parameters luma_model_describe lists; source and image_ref are for Luma models. Returns a run_id; call luma_run_await with it, and the outputs come back with an asset_id you can pass to any later call. NOT for video of any kind — use luma_generate_video; NOT for splitting an image into layers — use luma_generate_layering. Check luma_capability_list first: when a capability fits the task, run it with luma_session_run_capability, even for one image. Use this tool when none fits, or the user asks for a particular model.
luma_generate_layering
ChatGPTDecompose one image into ordered RGBA layers in a session you already opened. The image rides source — a URL, bytes, or an asset_id the workspace already holds — and prompt optionally guides how to split it; each layer comes back as its own output entry with an index (front-to-back, the last one is the background), a label and the bounds that re-composite the stack. Returns a run_id; call luma_run_await with it. NOT for creating or editing an image — use luma_generate_image; NOT for video — use luma_generate_video. Check luma_capability_list first: when a capability fits the task, run it with luma_session_run_capability, even for one layered image. Use this tool when none fits, or the user asks for a particular model.
luma_generate_video
ChatGPTCreate or modify one video clip in a session you already opened. type='video' generates a clip from the prompt, and extends an existing one when anchored on video.start_frame or video.end_frame; type='video_edit' restyles the clip in source; type='video_reframe' outpaints it to a new aspect ratio. A source can be an asset_id the workspace already holds. Name the model by a video row's id from luma_model_list. A third-party model takes prompt, aspect_ratio, duration, medias and the parameters luma_model_describe lists, and type='video'; video and source are for Luma models. Returns a run_id; call luma_run_await with it, and the outputs come back with an asset_id you can pass to any later call. NOT for still images — use luma_generate_image. Check luma_capability_list first: when a capability fits the task, run it with luma_session_run_capability, even for one video. Use this tool when none fits, or the user asks for a particular model.
luma_library_list_directory
ChatGPTYour team's asset library in Luma: the logos, brand files and approved media your team keeps. It stays the same across chats and sessions, unlike the session workspace that luma_workspace_list_assets reads. Lists one directory (default home): its direct contents, or with recursive everything under it. Pass the path or id of a directory from a previous result as directory to go deeper. Pass query to find files and directories by name; with recursive, it searches the whole tree under directory. Each file has a media: id; to look at a file, pass that id to luma_workspace_view_asset, and to use it in a generation, pass it as a source, in luma_session_send_brief's asset_ids, or in a capability's file field. Never pass a path where an id is asked for.
luma_library_make_directory
ChatGPTMake a directory in your team library. It changes your team's asset library in Luma, the one luma_library_list_directory browses, which stays the same across chats and sessions, unlike the session workspace that luma_workspace_list_assets reads. path may be nested, such as Campaigns/Spring: every directory on it is made, under parent (default home). Returns the deepest directory; pass its directory: id as directory to the other library tools.
luma_library_move
ChatGPTMove a file or directory into another directory of your team library; a directory moves with everything in it. It changes your team's asset library in Luma, the one luma_library_list_directory browses, which stays the same across chats and sessions, unlike the session workspace that luma_workspace_list_assets reads. Name items by the media: or directory: id luma_library_list_directory gave you, never by path. Returns the item where it now is.
luma_library_rename
ChatGPTRename a file or directory in your team library; it stays in its directory. It changes your team's asset library in Luma, the one luma_library_list_directory browses, which stays the same across chats and sessions, unlike the session workspace that luma_workspace_list_assets reads. Name items by the media: or directory: id luma_library_list_directory gave you, never by path. Returns the item under its new name.
luma_library_save_asset
ChatGPTKeep an asset from the session's workspace, such as a result you generated, in your team library. It changes your team's asset library in Luma, the one luma_library_list_directory browses, which stays the same across chats and sessions, unlike the session workspace that luma_workspace_list_assets reads. Pass directory (default home) and name to place it; saving the same asset to the same directory again returns the file already there. The file comes back pending or processing; call luma_workspace_view_asset with its media: id until it is ready before you use it, and pass that id, never its path, wherever a file is asked for.
luma_library_upload_asset
ChatGPTPut a file into your team library, such as a logo or a brand PDF. Pass exactly one source: url, size_bytes with mime_type and name for a file on your machine (PUT it where the answer's upload says, then call luma_workspace_complete_upload with the item's media: id), or data_base64 with mime_type and name for a small file you cannot send either way. It changes your team's asset library in Luma, the one luma_library_list_directory browses, which stays the same across chats and sessions, unlike the session workspace that luma_workspace_list_assets reads. Pass directory (default home) to place it. The file comes back pending or processing; call luma_workspace_view_asset with its media: id until it is ready before you use it, and pass that id, never its path, wherever a file is asked for.
luma_model_describe
ChatGPTOne model's guidance for one generation type — its strengths, weaknesses and prompting notes; read it when choosing a model and when writing the prompt — and what a third-party model takes on a generate call: a JSON Schema for its parameters (each one's type, allowed values or range, default and what it does) and the media roles it takes in medias. Pass values matching that schema as parameters on the generate call; aspect_ratio and (for video) duration are the generate tools' own fields, never parameters, and the values a model takes for them are its luma_model_list row's capabilities (aspect_ratios, durations_s). Luma models (uni-1, ray-3.2) list no parameters — their options are the tools' own fields. Get the model id from luma_model_list. Once a session is open, pass its session_id so the answer is what a run on that session accepts.
luma_model_list
ChatGPTImage and video models this connection can generate with, with what each supports (its capabilities field), credits per unit when known (pricing.estimate marks a rate the charge can differ from) and what each is known for (strengths). Pass a row's id as model to luma_generate_image (modality image) or luma_generate_video (modality video). Before choosing between models, call luma_model_describe on the candidates and read each one's guidance: its strengths, weaknesses and prompting notes. luma_model_describe also gives a third-party model's own options (quality, thinking level, audio) and the media roles it takes. Once a session is open, pass its session_id so the list is what a run on that session may use.
luma_run_await
ChatGPTWait up to timeout_s for a luma_generate_image / luma_generate_video / luma_generate_layering run to finish or fail. For briefs and capabilities, follow the session with luma_session_await instead: their runs are bookkeeping, and the session's assistant says when it is your turn. The run_id never changes — call again with the same one to keep waiting, which is safe after a timeout. Answers with the run's state and its outputs when it finished. When luma_run_await returns media_display=call_view_asset, call luma_workspace_view_asset with up to 4 of that run's image and video asset ids, or of its pending review's show assets, to display them in this host's viewer, then again with the next ids until all are shown. Talk to the user about their work, never about how it runs: say "the request", "the work" or "the result" instead of runs, sessions, apps' internal names, tool names, stages or error codes, and describe a service failure as a temporary problem on our side, without technical detail. Asset ids are handles for later tool calls; show one only when the user needs to point at a specific asset.
luma_run_respond
ChatGPTAnswer a request the session is waiting on: a review gate, a question or a client tool listed in luma_session_await's waiting (or luma_run_await's pending), by its run_id and invocation_id. A review is the user's decision: show them what it presents, ask, then fill result from their choice to match its answer_format, naming only its revision_targets; if their reply does not map onto it, ask them again. A result that does not fit is refused with the format. Then follow the session with luma_session_await, passing the seq this returns as after_seq. Talk to the user about their work, never about how it runs: say "the request", "the work" or "the result" instead of runs, sessions, apps' internal names, tool names, stages or error codes, and describe a service failure as a temporary problem on our side, without technical detail. Asset ids are handles for later tool calls; show one only when the user needs to point at a specific asset.
luma_session_await
ChatGPTTHE way to follow a session after luma_session_send_brief, luma_session_run_capability or luma_run_respond. Each call holds up to about 50 s. While the work goes on it answers status working with a short status_line you may show and nothing else: call it again right away with the same after_seq. Only your_turn, requires_action or ended carry what happened since after_seq (the assistant's messages, results with asset ids): tell the user, then pass next_after_seq next time; when has_more is true, call again with it to read the rest before acting. requires_action lists waiting items: a review or request is the user's decision: first show them the item's show assets with luma_workspace_view_asset, then ask them, fill answer_format from their choice and answer with luma_run_respond. When stop_reason is error, failure says what went wrong and the session stays open: tell the user, and offer to try again when failure.retryable is true. When this host has luma_workspace_view_asset, the image and video asset ids the events delivered are for its viewer; when luma_session_await returns media_display=call_view_asset, show the waiting items' show assets before asking the user. This host keeps only the last luma_workspace_view_asset call of each reply on screen, so call it once per reply: after the last run you are waiting on in the reply has finished, with every image and video to show from all of the reply's runs in that one call (up to 16 ids). Talk to the user about their work, never about how it runs: say "the request", "the work" or "the result" instead of runs, sessions, apps' internal names, tool names, stages or error codes, and describe a service failure as a temporary problem on our side, without technical detail. Asset ids are handles for later tool calls; show one only when the user needs to point at a specific asset.
luma_session_cancel
ChatGPTStop work. Pass run_id to cancel one run and keep the session open for the next brief; other runs on the session keep going. Pass session_id to cancel whatever the session is doing, and session_id with end=true to close it for good. Cancelling stops the run from using any more credits, and deletes nothing it already produced. Talk to the user about their work, never about how it runs: say "the request", "the work" or "the result" instead of runs, sessions, apps' internal names, tool names, stages or error codes, and describe a service failure as a temporary problem on our side, without technical detail. Asset ids are handles for later tool calls; show one only when the user needs to point at a specific asset.
luma_session_open
ChatGPTOpen a session with Luma for one workspace. THE ONLY TOOL THAT CREATES A SESSION — call it once per workspace and pass the session_id it returns to every other tool. workspace_key is optional: omitted, the session opens in your team's shared default workspace, created on first use; re-using a key re-uses that named workspace and its assets. To continue earlier work, find its workspace_key with luma_workspace_list first. End users who must not see each other's assets need a workspace_key each. Everything long-running afterwards is a run on this session: luma_generate_image / luma_generate_video / luma_generate_layering for one media call, luma_session_run_capability for a task one of Luma's capabilities fits, luma_session_send_brief for creative work no capability fits. Every run's outputs land in this workspace with an asset_id any later call can name. Returns a session_id and a resource URI to read.
luma_session_run_capability
ChatGPTRun one of Luma's capabilities on a brief, inside a session you already opened. The session's assistant starts it and relays what the capability says, asks and delivers. Follow the work with luma_session_await, passing the seq this returns as after_seq, and act when it says your_turn or requires_action. Prefer a fitting capability over luma_generate_image / luma_generate_video even when the deliverable is one image or video: a capability plans, generates and judges the task it is built for. Use a generate tool when no capability fits, or the user asks for a particular model. Never substitute a capability that cannot produce what was asked for. Get the slug from luma_capability_list, then use luma_capability_describe. Always pass the user's own words as brief, plus an object matching intake.input_schema as input when present. When one request asks for several independent pieces of work, run a separate capability for each, so each can be stopped or changed on its own. A field in input that takes a file, or a brief, can also name a team-library file by its media: id from luma_library_list_directory. Talk to the user about their work, never about how it runs: say "the request", "the work" or "the result" instead of runs, sessions, apps' internal names, tool names, stages or error codes, and describe a service failure as a temporary problem on our side, without technical detail. Asset ids are handles for later tool calls; show one only when the user needs to point at a specific asset.
luma_session_send_brief
ChatGPTBrief a session that is already open. Use it for multi-image or multi-shot requests no capability in luma_capability_list fits (a story in three images, a series that shares characters or a style): describe the whole set in one brief. Several images, or one image in several sizes or formats, often fit a capability; run that with luma_session_run_capability instead. The session's agent has the message history and any ref_artifacts, so a follow-up can revise, extend or re-cut an earlier output by referring to it, and can answer a clarification it asked for. Within what your session grant allows, it reaches the creative actions across the granted models — generating, editing, upscaling, reframing, trimming and stitching clips together, and audio: music, sound effects, voiceover, and lip-syncing a video to a voice track. For a single image or clip that no capability fits, call luma_generate_image or luma_generate_video directly. Send every user reply this way, including an answer to a question a capability asked: the assistant forwards it. Each brief runs an agent turn and bills to the session; one sent while a turn runs is taken after it. Returns at once; follow the work with luma_session_await, passing the seq this returns as after_seq, or keep the after_seq of a wait that answered working. A brief sent to a completed or expired session is refused with 410. Talk to the user about their work, never about how it runs: say "the request", "the work" or "the result" instead of runs, sessions, apps' internal names, tool names, stages or error codes, and describe a service failure as a temporary problem on our side, without technical detail. Asset ids are handles for later tool calls; show one only when the user needs to point at a specific asset.
luma_usage
ChatGPTHow many credits are left and which Luma team this connection uses, with the credits that team used in the current billing period. Pass session_id instead for the credits a session and everything spawned under it used, by part of the work, each named in words you can show the user; planning the work is the assistant's own model use, not a render, so never report it as a render charge. Pass asset_ids for the final charge of the job that made each generated image or video, and the total; asset_ids needs exactly one of session_id or workspace_id, naming the workspace that holds them. An asset reads credits null when its job has no final per-asset charge, because it is still running or its session bills as a whole; read that work with luma_usage(session_id). The team-wide answer is not available on a connection that declared a partner tenant. Talk to the user about their work, never about how it runs: say "the request", "the work" or "the result" instead of runs, sessions, apps' internal names, tool names, stages or error codes, and describe a service failure as a temporary problem on our side, without technical detail. Asset ids are handles for later tool calls; show one only when the user needs to point at a specific asset.
luma_workspace_complete_upload
ChatGPTFinish an upload made with size_bytes, after the PUT to its upload url succeeded. Once it answers, use the asset_id as a source as with any upload. If it answers that the bytes have not arrived, finish the PUT and call it again; if the upload url expired first, call the upload tool again with the same idempotency_key for a fresh one. Pass the asset_id luma_workspace_upload_asset answered with its session_id, or the media: id luma_library_upload_asset answered with no session_id.
luma_workspace_list
ChatGPTThe workspaces this connection can reach, newest first. Use it when the user asks which workspaces exist or wants to continue in an earlier one. Each one keeps its own assets and its own history, and luma_session_open takes the workspace_key of the one you pick. May be empty on a new connection; luma_session_open without a workspace_key creates your team's shared default workspace.
luma_workspace_list_assets
ChatGPTEverything the session's workspace holds — what you uploaded and what earlier runs produced — newest first. Read it before generating something the workspace may already have; each row's asset_id is the handle you pass as a source or in luma_session_send_brief's asset_ids. If luma_workspace_list_assets returns Session not found, this connection cannot use that session_id: retry with the id luma_session_open returned, and if that also fails, call luma_session_open again. Any other Not found means the catalog is unavailable; then describe only outputs verified in this chat, without inventing dashboard locations or creation times or promising reuse in a new chat. Talk to the user about their work, never about how it runs: say "the request", "the work" or "the result" instead of runs, sessions, apps' internal names, tool names, stages or error codes, and describe a service failure as a temporary problem on our side, without technical detail. Asset ids are handles for later tool calls; show one only when the user needs to point at a specific asset.
luma_workspace_upload_asset
ChatGPTPut a file into the session's workspace, so any run on this workspace can use it by its asset_id. Use it when the user hands you a file or a URL to work from: a hero image to edit, a brand PDF to brief from, a clip to re-cut. Pass exactly one source. url: the file is online. size_bytes with mime_type: the file is on your machine and you can run a shell command; the answer's upload says where to PUT it, then call luma_workspace_complete_upload with the asset_id. data_base64 with mime_type: a small file you cannot send either way; it shares url's size cap. If the upload url has expired, call again with the same idempotency_key for a fresh one; if the PUT already succeeded, do not PUT again, call luma_workspace_complete_upload. Returns the asset_id to pass as a source, in luma_session_send_brief's asset_ids or to luma_workspace_view_asset, and the file's intake state.
luma_workspace_view_asset
ChatGPTLook at up to 4 images or videos in the session's workspace, by asset_id from luma_run_await outputs, a waiting review's show, or luma_workspace_list_assets, or a team-library file's media: id from luma_library_list_directory; for more than 4, call it again with the next ids until all are shown. Returns an image of each asset — a video shows its thumbnail — and signed links. An asset still processing comes back with its state and no image or links; look again once its run finishes. An asset that failed comes back with state failed, rejection_reason and message; content_moderated means the same content will be rejected again. Call it when you need to see a result or luma_run_await's or luma_session_await's media_display asks for it, not after every run. On a host with a media viewer, the media is already shown to the user; reply with plain text and do not add a Markdown image, video, or duplicate thumbnail. session_id is needed only for workspace assets. Talk to the user about their work, never about how it runs: say "the request", "the work" or "the result" instead of runs, sessions, apps' internal names, tool names, stages or error codes, and describe a service failure as a temporary problem on our side, without technical detail. Asset ids are handles for later tool calls; show one only when the user needs to point at a specific asset.