Files

Upload a file

Changed on

Upload a file to your namespace, then reference it from a generation via ImageRef.file_id (as source, image_ref[], video.start_frame, keyframes, and so on). Two upload modes share this endpoint, selected by Content-Type:

  • multipart/form-data — send the bytes inline in the file part. Best for small files (subject to an inline size cap; larger files must use the presigned flow). The returned file is already pending ingest.

  • application/json — request a presigned upload. The response upload envelope tells you where to PUT the bytes; afterward call POST /files/{file_id}/complete to start ingest. Use this for larger files.

post/files

Request

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

Request body

filenamestring nullable

Optional original filename to record.

mime_typestring required

MIME type of the bytes you will upload.

size_bytesinteger required

Exact size in bytes of the object you will PUT. Up to 5 GiB (the S3 single-PUT ceiling).

purpose'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.

expires_atstring date-time nullable

Optional TTL. After this time Luma may automatically delete the file and reclaim its bytes.

user_idstring nullable

Optional opaque end-user tag for abuse attribution. Mirrors the user_id field on POST /generations.

Response

File created

idstring uuid required

File identifier.

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.

Changes