Files

Upload a file

client.Files.New(ctx, body) (*CreateFileResponse, error)

POST/files

List files

client.Files.List(ctx, query) (*FileList, error)

GET/files

Complete a presigned upload

client.Files.Complete(ctx, fileID) (*File, error)

POST/files/{file_id}/complete

Get a file

client.Files.Get(ctx, fileID) (*File, error)

GET/files/{file_id}

Delete a file

client.Files.Delete(ctx, fileID) error

DELETE/files/{file_id}

ModelsExpandCollapse

type CreateFileResponse struct{…}

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.

format: uuid

File File

A file in the caller's namespace.

ID string

File identifier, referenced as ImageRef.file_id.

format: uuid

CreatedAt Time

Creation timestamp.

format: date-time

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

const FilePurposeInput FilePurpose = "input"

const FilePurposeReference FilePurpose = "reference"

SizeBytes int64

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 once the file has been deleted.

One of the following:

const FileStatePending FileState = "pending"

const FileStateReady FileState = "ready"

const FileStateFailed FileState = "failed"

const FileStateDeleted FileState = "deleted"

DeletedAt Time

optional

When the file was deleted; null otherwise.

format: date-time

ExpiresAt Time

optional

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.

format: date-time

FailureReason string

optional

Human-readable reason when state is failed.

Filename string

optional

Original filename supplied at upload, if any.

UserID string

optional

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 once the file has been deleted.

One of the following:

const FileStatePending FileState = "pending"

const FileStateReady FileState = "ready"

const FileStateFailed FileState = "failed"

const FileStateDeleted FileState = "deleted"

Upload PresignedUpload

optional

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.

ExpiresAt Time

When the presigned URL expires.

format: date-time

Method string

HTTP method to use for the upload — always PUT.

URL string

Presigned S3 URL to PUT the bytes to.

format: uri

Headers map[string, string]

optional

Headers that must be sent with the PUT request.

type File struct{…}

A file in the caller's namespace.

ID string

File identifier, referenced as ImageRef.file_id.

format: uuid

CreatedAt Time

Creation timestamp.

format: date-time

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

const FilePurposeInput FilePurpose = "input"

const FilePurposeReference FilePurpose = "reference"

SizeBytes int64

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 once the file has been deleted.

One of the following:

const FileStatePending FileState = "pending"

const FileStateReady FileState = "ready"

const FileStateFailed FileState = "failed"

const FileStateDeleted FileState = "deleted"

DeletedAt Time

optional

When the file was deleted; null otherwise.

format: date-time

ExpiresAt Time

optional

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.

format: date-time

FailureReason string

optional

Human-readable reason when state is failed.

Filename string

optional

Original filename supplied at upload, if any.

UserID string

optional

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

type FileList struct{…}

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 []File

Files in this page.

ID string

File identifier, referenced as ImageRef.file_id.

format: uuid

CreatedAt Time

Creation timestamp.

format: date-time

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

const FilePurposeInput FilePurpose = "input"

const FilePurposeReference FilePurpose = "reference"

SizeBytes int64

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 once the file has been deleted.

One of the following:

const FileStatePending FileState = "pending"

const FileStateReady FileState = "ready"

const FileStateFailed FileState = "failed"

const FileStateDeleted FileState = "deleted"

DeletedAt Time

optional

When the file was deleted; null otherwise.

format: date-time

ExpiresAt Time

optional

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.

format: date-time

FailureReason string

optional

Human-readable reason when state is failed.

Filename string

optional

Original filename supplied at upload, if any.

UserID string

optional

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

HasMore bool

Whether more files exist beyond this page.

NextCursor string

optional

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

type FilePurpose string

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:

const FilePurposeInput FilePurpose = "input"

const FilePurposeReference FilePurpose = "reference"

type FileState string

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 once the file has been deleted.

One of the following:

const FileStatePending FileState = "pending"

const FileStateReady FileState = "ready"

const FileStateFailed FileState = "failed"

const FileStateDeleted FileState = "deleted"

type PresignedUpload struct{…}

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.

ExpiresAt Time

When the presigned URL expires.

format: date-time

Method string

HTTP method to use for the upload — always PUT.

URL string

Presigned S3 URL to PUT the bytes to.

format: uri

Headers map[string, string]

optional

Headers that must be sent with the PUT request.