API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Files

Upload a file

files.create(FileCreateParams**kwargs) -> CreateFileResponse

POST/files

List files

files.list(FileListParams**kwargs) -> FileList

GET/files

Complete a presigned upload

files.complete(strfile_id) -> File

POST/files/{file_id}/complete

Get a file

files.get(strfile_id) -> File

GET/files/{file_id}

Delete a file

files.delete(strfile_id)

DELETE/files/{file_id}

ModelsExpand Collapse

class CreateFileResponse: …

Result of POST /files. In the multipart (inline) flow upload is null and the file is already pending ingest. In the presigned (JSON) flow upload carries the PUT envelope and the file stays pending until you call POST /files/{file_id}/complete. Top-level id and state are conveniences that mirror file.id and file.state; the full record is always under file.

id: str

File identifier.

formatuuid

file: File

A file in the caller's namespace.

id: str

File identifier, referenced as ImageRef.file_id.

formatuuid

created_at: datetime

Creation timestamp.

formatdate-time

mime_type: str

MIME type of the stored bytes (for example, image/jpeg).

purpose: FilePurpose

How the file is intended to be used in a generation. input is the primary subject (e.g. the source image for an edit); reference is style/content guidance.

One of the following:

"input"

"reference"

size_bytes: int

Size of the stored object in bytes.

state: FileState

Lifecycle state of an uploaded file. pending until bytes are received and the ingest pipeline runs; ready once it can be referenced from a generation; failed if ingest/moderation rejected it; deleted after a soft-delete.

One of the following:

"pending"

"ready"

"failed"

"deleted"

deleted_at: Optional[datetime]

Soft-delete timestamp, if the file was deleted.

formatdate-time

expires_at: Optional[datetime]

TTL set at upload, if any. After this time Luma may automatically delete the file and reclaim its bytes — you don't need to call DELETE yourself.

formatdate-time

failure_reason: Optional[str]

Human-readable reason when state is failed.

filename: Optional[str]

Original filename supplied at upload, if any.

user_id: Optional[str]

The opaque end-user tag supplied at upload, echoed back unchanged. Abuse-attribution only; not an access-control primitive.

state: FileState

Lifecycle state of an uploaded file. pending until bytes are received and the ingest pipeline runs; ready once it can be referenced from a generation; failed if ingest/moderation rejected it; deleted after a soft-delete.

One of the following:

"pending"

"ready"

"failed"

"deleted"

upload: Optional[PresignedUpload]

Where to PUT the file bytes for a presigned (JSON) upload. Issue an HTTP PUT of the raw bytes to url with the given headers, then call POST /files/{file_id}/complete.

expires_at: datetime

When the presigned URL expires.

formatdate-time

method: str

HTTP method to use for the upload — always PUT.

url: str

Presigned S3 URL to PUT the bytes to.

formaturi

headers: Optional[Dict[str, str]]

Headers that must be sent with the PUT request.

class File: …

A file in the caller's namespace.

id: str

File identifier, referenced as ImageRef.file_id.

formatuuid

created_at: datetime

Creation timestamp.

formatdate-time

mime_type: str

MIME type of the stored bytes (for example, image/jpeg).

purpose: FilePurpose

How the file is intended to be used in a generation. input is the primary subject (e.g. the source image for an edit); reference is style/content guidance.

One of the following:

"input"

"reference"

size_bytes: int

Size of the stored object in bytes.

state: FileState

Lifecycle state of an uploaded file. pending until bytes are received and the ingest pipeline runs; ready once it can be referenced from a generation; failed if ingest/moderation rejected it; deleted after a soft-delete.

One of the following:

"pending"

"ready"

"failed"

"deleted"

deleted_at: Optional[datetime]

Soft-delete timestamp, if the file was deleted.

formatdate-time

expires_at: Optional[datetime]

TTL set at upload, if any. After this time Luma may automatically delete the file and reclaim its bytes — you don't need to call DELETE yourself.

formatdate-time

failure_reason: Optional[str]

Human-readable reason when state is failed.

filename: Optional[str]

Original filename supplied at upload, if any.

user_id: Optional[str]

The opaque end-user tag supplied at upload, echoed back unchanged. Abuse-attribution only; not an access-control primitive.

class FileList: …

Keyset-paginated page of files, newest first. When has_more is true, pass next_cursor back as the cursor query parameter to fetch the next page. next_cursor is opaque.

data: List[File]

Files in this page.

id: str

File identifier, referenced as ImageRef.file_id.

formatuuid

created_at: datetime

Creation timestamp.

formatdate-time

mime_type: str

MIME type of the stored bytes (for example, image/jpeg).

purpose: FilePurpose

How the file is intended to be used in a generation. input is the primary subject (e.g. the source image for an edit); reference is style/content guidance.

One of the following:

"input"

"reference"

size_bytes: int

Size of the stored object in bytes.

state: FileState

Lifecycle state of an uploaded file. pending until bytes are received and the ingest pipeline runs; ready once it can be referenced from a generation; failed if ingest/moderation rejected it; deleted after a soft-delete.

One of the following:

"pending"

"ready"

"failed"

"deleted"

deleted_at: Optional[datetime]

Soft-delete timestamp, if the file was deleted.

formatdate-time

expires_at: Optional[datetime]

TTL set at upload, if any. After this time Luma may automatically delete the file and reclaim its bytes — you don't need to call DELETE yourself.

formatdate-time

failure_reason: Optional[str]

Human-readable reason when state is failed.

filename: Optional[str]

Original filename supplied at upload, if any.

user_id: Optional[str]

The opaque end-user tag supplied at upload, echoed back unchanged. Abuse-attribution only; not an access-control primitive.

has_more: bool

Whether more files exist beyond this page.

next_cursor: Optional[str]

Opaque cursor for the next page, when has_more is true.

Literal["input", "reference"]

How the file is intended to be used in a generation. input is the primary subject (e.g. the source image for an edit); reference is style/content guidance.

One of the following:

"input"

"reference"

Literal["pending", "ready", "failed", "deleted"]

Lifecycle state of an uploaded file. pending until bytes are received and the ingest pipeline runs; ready once it can be referenced from a generation; failed if ingest/moderation rejected it; deleted after a soft-delete.

One of the following:

"pending"

"ready"

"failed"

"deleted"

class PresignedUpload: …

Where to PUT the file bytes for a presigned (JSON) upload. Issue an HTTP PUT of the raw bytes to url with the given headers, then call POST /files/{file_id}/complete.

expires_at: datetime

When the presigned URL expires.

formatdate-time

method: str

HTTP method to use for the upload — always PUT.

url: str

Presigned S3 URL to PUT the bytes to.

formaturi

headers: Optional[Dict[str, str]]

Headers that must be sent with the PUT request.