Skip to content
Luma Agents
lumalabs.ai
API Reference
Files

Get a file

$ luma-agents-cli files get
GET/files/{file_id}

Retrieve metadata for a single file in your namespace.

ParametersExpand Collapse
--file-id: string

File UUID.

ReturnsExpand Collapse
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.

created_at: string

Creation timestamp.

mime_type: string

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

purpose: "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.

"input"
"reference"
size_bytes: number

Size of the stored object in bytes.

state: "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.

"pending"
"ready"
"failed"
"deleted"
deleted_at: optional string

Soft-delete timestamp, if the file was deleted.

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.

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.

Get a file

luma-agents-cli files get \
  --auth-token 'My Auth Token' \
  --file-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e
{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "created_at": "2019-12-27T18:11:19.117Z",
  "mime_type": "mime_type",
  "purpose": "input",
  "size_bytes": 0,
  "state": "pending",
  "deleted_at": "2019-12-27T18:11:19.117Z",
  "expires_at": "2019-12-27T18:11:19.117Z",
  "failure_reason": "failure_reason",
  "filename": "filename",
  "user_id": "user_id"
}
Returns Examples
{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "created_at": "2019-12-27T18:11:19.117Z",
  "mime_type": "mime_type",
  "purpose": "input",
  "size_bytes": 0,
  "state": "pending",
  "deleted_at": "2019-12-27T18:11:19.117Z",
  "expires_at": "2019-12-27T18:11:19.117Z",
  "failure_reason": "failure_reason",
  "filename": "filename",
  "user_id": "user_id"
}