Skip to content
Luma Agents
lumalabs.ai
API Reference
Files

Upload a file

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

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.

ParametersExpand Collapse
mime_type: str

MIME type of the bytes you will upload.

minLength1
maxLength256
size_bytes: int

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

minimum1
expires_at: Optional[Union[str, datetime, null]]

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

formatdate-time
filename: Optional[str]

Optional original filename to record.

maxLength512
purpose: Optional[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"
user_id: Optional[str]

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

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

Upload a file

import os
from luma_agents import Luma

client = Luma(
    auth_token=os.environ.get("LUMA_AGENTS_API_KEY"),  # This is the default and can be omitted
)
create_file_response = client.files.create(
    mime_type="x",
    size_bytes=1,
)
print(create_file_response.id)
{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "file": {
    "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"
  },
  "state": "pending",
  "upload": {
    "expires_at": "2019-12-27T18:11:19.117Z",
    "method": "method",
    "url": "https://example.com",
    "headers": {
      "foo": "string"
    }
  }
}
Returns Examples
{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "file": {
    "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"
  },
  "state": "pending",
  "upload": {
    "expires_at": "2019-12-27T18:11:19.117Z",
    "method": "method",
    "url": "https://example.com",
    "headers": {
      "foo": "string"
    }
  }
}