# Files ## Upload a file `client.Files.New(ctx, body) (*CreateFileResponse, error)` **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. ### Parameters - `body FileNewParams` - `MimeType param.Field[string]` MIME type of the bytes you will upload. - `SizeBytes param.Field[int64]` Exact size in bytes of the object you will PUT. Up to 5 GiB (the S3 single-PUT ceiling). - `ExpiresAt param.Field[Time]` Optional TTL. After this time Luma may automatically delete the file and reclaim its bytes. - `Filename param.Field[string]` Optional original filename to record. - `Purpose param.Field[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. - `UserID param.Field[string]` Optional opaque end-user tag for abuse attribution. Mirrors the user_id field on POST /generations. ### Returns - `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. - `File File` A file in the caller's namespace. - `ID string` File identifier, referenced as ImageRef.file_id. - `CreatedAt Time` Creation timestamp. - `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. - `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` after a soft-delete. - `const FileStatePending FileState = "pending"` - `const FileStateReady FileState = "ready"` - `const FileStateFailed FileState = "failed"` - `const FileStateDeleted FileState = "deleted"` - `DeletedAt Time` Soft-delete timestamp, if the file was deleted. - `ExpiresAt Time` 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. - `FailureReason string` Human-readable reason when state is failed. - `Filename string` Original filename supplied at upload, if any. - `UserID string` 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. - `Upload 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. - `ExpiresAt Time` When the presigned URL expires. - `Method string` HTTP method to use for the upload — always PUT. - `URL string` Presigned S3 URL to PUT the bytes to. - `Headers map[string, string]` Headers that must be sent with the PUT request. ### Example ```go package main import ( "context" "fmt" "github.com/lumalabs/luma-agents-go" "github.com/lumalabs/luma-agents-go/option" ) func main() { client := lumaagents.NewClient( option.WithAuthToken("My Auth Token"), ) createFileResponse, err := client.Files.New(context.TODO(), lumaagents.FileNewParams{ MimeType: lumaagents.F("x"), SizeBytes: lumaagents.F(int64(1)), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", createFileResponse.ID) } ``` #### Response ```json { "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" } } } ``` ## List files `client.Files.List(ctx, query) (*FileList, error)` **get** `/files` List the files in your namespace, newest first. Keyset-paginated: when has_more is true, pass next_cursor back as cursor. ### Parameters - `query FileListParams` - `Cursor param.Field[string]` Opaque pagination cursor from a prior response's next_cursor. - `Limit param.Field[int64]` Maximum files to return (1–100). Defaults to 25. - `Purpose param.Field[FilePurpose]` Filter to files with this purpose. - `State param.Field[FileState]` Filter to files in this state. ### Returns - `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. - `CreatedAt Time` Creation timestamp. - `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. - `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` after a soft-delete. - `const FileStatePending FileState = "pending"` - `const FileStateReady FileState = "ready"` - `const FileStateFailed FileState = "failed"` - `const FileStateDeleted FileState = "deleted"` - `DeletedAt Time` Soft-delete timestamp, if the file was deleted. - `ExpiresAt Time` 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. - `FailureReason string` Human-readable reason when state is failed. - `Filename string` Original filename supplied at upload, if any. - `UserID string` 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` Opaque cursor for the next page, when has_more is true. ### Example ```go package main import ( "context" "fmt" "github.com/lumalabs/luma-agents-go" "github.com/lumalabs/luma-agents-go/option" ) func main() { client := lumaagents.NewClient( option.WithAuthToken("My Auth Token"), ) fileList, err := client.Files.List(context.TODO(), lumaagents.FileListParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fileList.Data) } ``` #### Response ```json { "data": [ { "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" } ], "has_more": true, "next_cursor": "next_cursor" } ``` ## Complete a presigned upload `client.Files.Complete(ctx, fileID) (*File, error)` **post** `/files/{file_id}/complete` Finalize a presigned upload after you have PUT the bytes to the upload URL. Kicks off ingest/moderation and returns the file, which transitions to `ready` (or `failed`) asynchronously — poll GET /files/{file_id} to observe the terminal state. ### Parameters - `fileID string` ### Returns - `type File struct{…}` A file in the caller's namespace. - `ID string` File identifier, referenced as ImageRef.file_id. - `CreatedAt Time` Creation timestamp. - `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. - `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` after a soft-delete. - `const FileStatePending FileState = "pending"` - `const FileStateReady FileState = "ready"` - `const FileStateFailed FileState = "failed"` - `const FileStateDeleted FileState = "deleted"` - `DeletedAt Time` Soft-delete timestamp, if the file was deleted. - `ExpiresAt Time` 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. - `FailureReason string` Human-readable reason when state is failed. - `Filename string` Original filename supplied at upload, if any. - `UserID string` The opaque end-user tag supplied at upload, echoed back unchanged. Abuse-attribution only; not an access-control primitive. ### Example ```go package main import ( "context" "fmt" "github.com/lumalabs/luma-agents-go" "github.com/lumalabs/luma-agents-go/option" ) func main() { client := lumaagents.NewClient( option.WithAuthToken("My Auth Token"), ) file, err := client.Files.Complete(context.TODO(), "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", file.ID) } ``` #### Response ```json { "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" } ``` ## Get a file `client.Files.Get(ctx, fileID) (*File, error)` **get** `/files/{file_id}` Retrieve metadata for a single file in your namespace. ### Parameters - `fileID string` ### Returns - `type File struct{…}` A file in the caller's namespace. - `ID string` File identifier, referenced as ImageRef.file_id. - `CreatedAt Time` Creation timestamp. - `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. - `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` after a soft-delete. - `const FileStatePending FileState = "pending"` - `const FileStateReady FileState = "ready"` - `const FileStateFailed FileState = "failed"` - `const FileStateDeleted FileState = "deleted"` - `DeletedAt Time` Soft-delete timestamp, if the file was deleted. - `ExpiresAt Time` 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. - `FailureReason string` Human-readable reason when state is failed. - `Filename string` Original filename supplied at upload, if any. - `UserID string` The opaque end-user tag supplied at upload, echoed back unchanged. Abuse-attribution only; not an access-control primitive. ### Example ```go package main import ( "context" "fmt" "github.com/lumalabs/luma-agents-go" "github.com/lumalabs/luma-agents-go/option" ) func main() { client := lumaagents.NewClient( option.WithAuthToken("My Auth Token"), ) file, err := client.Files.Get(context.TODO(), "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", file.ID) } ``` #### Response ```json { "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" } ``` ## Delete a file `client.Files.Delete(ctx, fileID) error` **delete** `/files/{file_id}` Soft-delete a file. It can no longer be referenced from new generations. Returns 204 with no body. ### Parameters - `fileID string` ### Example ```go package main import ( "context" "github.com/lumalabs/luma-agents-go" "github.com/lumalabs/luma-agents-go/option" ) func main() { client := lumaagents.NewClient( option.WithAuthToken("My Auth Token"), ) err := client.Files.Delete(context.TODO(), "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e") if err != nil { panic(err.Error()) } } ``` ## Domain Types ### Create File Response - `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. - `File File` A file in the caller's namespace. - `ID string` File identifier, referenced as ImageRef.file_id. - `CreatedAt Time` Creation timestamp. - `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. - `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` after a soft-delete. - `const FileStatePending FileState = "pending"` - `const FileStateReady FileState = "ready"` - `const FileStateFailed FileState = "failed"` - `const FileStateDeleted FileState = "deleted"` - `DeletedAt Time` Soft-delete timestamp, if the file was deleted. - `ExpiresAt Time` 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. - `FailureReason string` Human-readable reason when state is failed. - `Filename string` Original filename supplied at upload, if any. - `UserID string` 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. - `Upload 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. - `ExpiresAt Time` When the presigned URL expires. - `Method string` HTTP method to use for the upload — always PUT. - `URL string` Presigned S3 URL to PUT the bytes to. - `Headers map[string, string]` Headers that must be sent with the PUT request. ### File - `type File struct{…}` A file in the caller's namespace. - `ID string` File identifier, referenced as ImageRef.file_id. - `CreatedAt Time` Creation timestamp. - `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. - `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` after a soft-delete. - `const FileStatePending FileState = "pending"` - `const FileStateReady FileState = "ready"` - `const FileStateFailed FileState = "failed"` - `const FileStateDeleted FileState = "deleted"` - `DeletedAt Time` Soft-delete timestamp, if the file was deleted. - `ExpiresAt Time` 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. - `FailureReason string` Human-readable reason when state is failed. - `Filename string` Original filename supplied at upload, if any. - `UserID string` The opaque end-user tag supplied at upload, echoed back unchanged. Abuse-attribution only; not an access-control primitive. ### File List - `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. - `CreatedAt Time` Creation timestamp. - `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. - `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` after a soft-delete. - `const FileStatePending FileState = "pending"` - `const FileStateReady FileState = "ready"` - `const FileStateFailed FileState = "failed"` - `const FileStateDeleted FileState = "deleted"` - `DeletedAt Time` Soft-delete timestamp, if the file was deleted. - `ExpiresAt Time` 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. - `FailureReason string` Human-readable reason when state is failed. - `Filename string` Original filename supplied at upload, if any. - `UserID string` 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` Opaque cursor for the next page, when has_more is true. ### File Purpose - `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. - `const FilePurposeInput FilePurpose = "input"` - `const FilePurposeReference FilePurpose = "reference"` ### File State - `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` after a soft-delete. - `const FileStatePending FileState = "pending"` - `const FileStateReady FileState = "ready"` - `const FileStateFailed FileState = "failed"` - `const FileStateDeleted FileState = "deleted"` ### Presigned Upload - `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. - `Method string` HTTP method to use for the upload — always PUT. - `URL string` Presigned S3 URL to PUT the bytes to. - `Headers map[string, string]` Headers that must be sent with the PUT request.