API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Files

Upload a file

POST/files

List files

GET/files

Complete a presigned upload

POST/files/{file_id}/complete

Get a file

GET/files/{file_id}

Delete a file

DELETE/files/{file_id}

ModelsExpand Collapse

CreateFileResponse = object { id, file, state, upload }

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: string

File identifier.

formatuuid

file: File { id, created_at, mime_type, 8 more }

A file in the caller's namespace.

id: string

File identifier, referenced as ImageRef.file_id.

formatuuid

created_at: string

Creation timestamp.

formatdate-time

mime_type: string

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: number

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 string

Soft-delete timestamp, if the file was deleted.

formatdate-time

expires_at: optional string

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 string

Human-readable reason when state is failed.

filename: optional string

Original filename supplied at upload, if any.

user_id: optional string

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 { expires_at, method, url, headers }

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: string

When the presigned URL expires.

formatdate-time

method: string

HTTP method to use for the upload — always PUT.

url: string

Presigned S3 URL to PUT the bytes to.

formaturi

headers: optional map[string]

Headers that must be sent with the PUT request.

File = object { id, created_at, mime_type, 8 more }

A file in the caller's namespace.

id: string

File identifier, referenced as ImageRef.file_id.

formatuuid

created_at: string

Creation timestamp.

formatdate-time

mime_type: string

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: number

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 string

Soft-delete timestamp, if the file was deleted.

formatdate-time

expires_at: optional string

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 string

Human-readable reason when state is failed.

filename: optional string

Original filename supplied at upload, if any.

user_id: optional string

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

FileList = object { data, has_more, next_cursor }

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: array of File { id, created_at, mime_type, 8 more }

Files in this page.

id: string

File identifier, referenced as ImageRef.file_id.

formatuuid

created_at: string

Creation timestamp.

formatdate-time

mime_type: string

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: number

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 string

Soft-delete timestamp, if the file was deleted.

formatdate-time

expires_at: optional string

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 string

Human-readable reason when state is failed.

filename: optional string

Original filename supplied at upload, if any.

user_id: optional string

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

has_more: boolean

Whether more files exist beyond this page.

next_cursor: optional string

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

FilePurpose = "input" or "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"

FileState = "pending" or "ready" or "failed" or "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"

PresignedUpload = object { expires_at, method, url, headers }

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: string

When the presigned URL expires.

formatdate-time

method: string

HTTP method to use for the upload — always PUT.

url: string

Presigned S3 URL to PUT the bytes to.

formaturi

headers: optional map[string]

Headers that must be sent with the PUT request.