Files

Get a file

Changed on

Retrieve metadata for a single file in your namespace.

get/files/{file_id}

Request

  • Base URL: https://agents.lumalabs.ai/v1
  • URL: https://agents.lumalabs.ai/v1/files/{file_id}
  • Auth: HTTP bearer

Path parameters

file_idstring uuid required

File UUID.

Response

File metadata

idstring uuid required

File identifier, referenced as ImageRef.file_id.

filenamestring nullable

Original filename supplied at upload, if any.

mime_typestring required

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

size_bytesinteger required

Size of the stored object in bytes.

purpose'input' | 'reference' required

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.

state'pending' | 'ready' | 'failed' | 'deleted' required

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.

failure_reasonstring nullable

Human-readable reason when state is failed.

expires_atstring date-time nullable

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.

created_atstring date-time required

Creation timestamp.

deleted_atstring date-time nullable

Soft-delete timestamp, if the file was deleted.

user_idstring nullable

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

Changes