Luma API Python + CLI Client Reference¶

This is a Python and CLI client for the Luma API. Both are included in the pure-Python library lumaapi, which you can install from PyPI:

pip install lumaapi

We assume you already have Python 3 with pip installed.

Example CLI usage¶

# Check credits
luma credits
# Submit video, zip, or folder (of images). Prints slug
luma submit <path> <title>
# Check status of slug
luma status <slug>

If not already logged in, you will be prompted for an API key. You may obtain one from the Luma API dashboard. You may also manually authenticate with

luma auth <api-key>

Example usage inside Python¶

from lumaapi import LumaClient
client = LumaClient(api_key)
slug = client.submit(video_path, title)
print(client.status(slug))

Again, you may obtain an API key from the Luma API dashboard. Any of the functions in LumaClient may be used directly in the CLI e.g.

client.submit(video_path, title)
luma submit video_path title

Please see detailed per-function documentation below.

LumaClient¶

class LumaClient(api_key=None, is_cli=False, use_cache=True)¶

Luma API Python Client. Currently limited to basic video/zip/folder uploads and status checking.

Library usage:

from lumaapi import LumaClient
client = LumaClient(api_key)
slug = client.submit(video_path, title)
print(client.status(slug))

CLI usage: To submit a video

luma submit <path> <title>

where path can be a video, zip, or directory. This outputs a slug.

To check status of the capture

luma status <slug>

To search user’s captures

luma get <title>

To manually authenticate (the CLI automatically prompts for api-key when running anything else)

luma auth

To check for credits

luma credits

Parameters:

api_key (Optional[str]) – API key. If None, will be requested when needed
is_cli (bool) – Whether this is being used as a CLI (internal use only)
use_cache (bool) – Whether to cache the auth headers (default True)

credits()¶

luma credits

Get number of credits remaining for the user.

Returns:: LumaCreditInfo
Return type:: LumaCreditInfo

auth(api_key=None)¶

luma auth [api-key]

Update the api_key to the provided api_key. Alternatively, if api_key is not given, load the cached API key, or ask the user to enter it If api_key is updated, runs client.credits() to check its validity.

Parameters:: api_key (Optional[str]) – str, optional, API key to use instead of prompting user
Returns:: dict, headers to use for authenticated requests (Authorization: luma-api-key=<api_key>)
Return type:: Dict[str, str]

clear_auth()¶

luma clear-auth

Remove cached authorization (auth()) if present

submit(path, title, cam_model=CameraType.NORMAL, silent=False)¶

luma submit <path> <title>

Submit a video, zip, or directory (at path) to Luma for processing, with given title. User might be prompted for API key, if not already authenticated (call auth). Returns the slug. After submissing, use status(slug) to check the status and output artifacts.

Parameters:

path (str) – str, path to video, zip of images, zip of multiple videos, or directory (with images) to submit
title (str) – str, a descriptive title for the capture
cam_model (CameraType) – CameraType, camera model
silent (bool) – bool, if True, do not print progress

Returns:

str, the slug identifier for checking the status etc

Return type:

str

submit_binary(payload, title, cam_model=CameraType.NORMAL, silent=False)¶

[Python only] Submit a video or zip (as binary blob) to Luma for processing, with given title. User might be prompted for API key, if not already authenticated (call auth). Returns the slug. After submissing, use status(slug) to check the status and output artifacts.

Parameters:

payload (bytes) – bytes,
title (str) – str, a descriptive title for the capture
cam_model (CameraType) – CameraType, camera model
silent (bool) –

Returns:

str, the slug identifier for checking the status etc

Return type:

str

status(slug)¶

luma status <slug>

Check the status of a submitted capture

Parameters:: slug (str) – str, slug of capture to check (from submit())
Returns:: LumaCaptureInfo dataclass
Return type:: LumaCaptureInfo

get(query='', skip=0, take=50, desc=True)¶

luma get <query>

Find captures from all of the user’s API captures

Parameters:

query (str) – str, query string to filter captures by (title)
skip (int) – int, starting capture index
take (int) – int, number of captures to take
desc (bool) – bool, whether to sort in descending order

Returns:

list of LumaCaptureInfo dataclass

Return type:

List[LumaCaptureInfo]

Misc Types¶

class LumaCreditInfo(remaining, used, total)¶

Response of credits query

Parameters:

remaining (int) –
used (int) –
total (int) –

remaining: int¶: Number of remaining credits

used: int¶: Number of used credits

total: int¶: Number of remaining+used credits

class LumaCaptureInfo(title: str, type: lumaapi.CaptureType, location: Optional[lumaapi.CaptureLocation], privacy: lumaapi.PrivacyLevel, date: datetime.datetime, username: str, status: lumaapi.CaptureStatus, latest_run: Optional[lumaapi.LumaRunInfo])¶

Parameters:

title (str) –
type (CaptureType) –
location (Optional[CaptureLocation]) –
privacy (PrivacyLevel) –
date (datetime) –
username (str) –
status (CaptureStatus) –
latest_run (Optional[LumaRunInfo]) –

title: str¶: Capture title

type: CaptureType¶: Capture type. This will currently be reconstruction

location: Optional[CaptureLocation]¶: Location of capture. For API captures, this will be None

privacy: PrivacyLevel¶: Capture privacy level

date: datetime¶: Capture creation time

username: str¶: Username of submitting user

status: CaptureStatus¶: Capture upload status

class LumaRunInfo(status: lumaapi.RunStatus, progress: int, current_stage: str, artifacts: List[Dict[str, str]])¶

Parameters:

status (RunStatus) –
progress (int) –
current_stage (str) –
artifacts (List[Dict[str, str]]) –

status: RunStatus¶: Status of run

progress: int¶: Percentage progress (0-100)

current_stage: str¶: Current stage of reconstruction for information. Examples are sfm and nerf

artifacts: List[Dict[str, str]]¶: List of output artifacts (each entry has keys type and url)

enum PrivacyLevel(value)¶

Privacy levels for capture

Valid values are as follows:

PRIVATE = <PrivacyLevel.PRIVATE: 'private'>¶: Fully private (default)

UNLISTED = <PrivacyLevel.UNLISTED: 'unlisted'>¶: Unlisted. Sharable by link

PUBLIC = <PrivacyLevel.PUBLIC: 'public'>¶: Shows up in feeds and can be featured

OPEN = <PrivacyLevel.OPEN: 'open'>¶: Can be remixed by other users

enum CaptureStatus(value)¶

Capture upload status. Not to be confused with RunStatus

Valid values are as follows:

NEW = <CaptureStatus.NEW: 0>¶: New capture, not uploaded

UPLOADING = <CaptureStatus.UPLOADING: 1>¶: Capture is uploading

COMPLETE = <CaptureStatus.COMPLETE: 2>¶: Capture has finished uploading

enum RunStatus(value)¶

Capture run status

Valid values are as follows:

NEW = <RunStatus.NEW: 0>¶: New run in queue

DISPATCHED = <RunStatus.DISPATCHED: 1>¶: Run dispatched to worker

FAILED = <RunStatus.FAILED: 2>¶: Run failed

FINISHED = <RunStatus.FINISHED: 3>¶: Run finished

enum CaptureType(value)¶

Capture types. Current API version always has RECONSTRUCTION type

Valid values are as follows:

RECONSTRUCTION = <CaptureType.RECONSTRUCTION: 0>¶: This is the only option

enum CameraType(value)¶

Camera types

Valid values are as follows:

NORMAL = <CameraType.NORMAL: 'normal'>¶: Perspective camera

FISHEYE = <CameraType.FISHEYE: 'fisheye'>¶: Fisheye camera

EQUIRECTANGULAR = <CameraType.EQUIRECTANGULAR: 'equirectangular'>¶: Equirectangular 360 camera

class CaptureLocation(latitude=0.0, longitude=0.0, name='', is_visible=True)¶

Capture location information. Current API uploads will not have this information.

Parameters:

latitude (float) –
longitude (float) –
name (str) –
is_visible (bool) –

latitude: float = 0.0¶: Latitude in deg

longitude: float = 0.0¶: Longitude in deg

name: str = ''¶: Name of location if available

is_visible: bool = True¶: Whether location is visible to other users

Note: This doc uses Ruilong Li’s fork of the PyTorch Sphinx theme used for nerfacc