release: 0.4.0

[stainless-app]

Automated Release PR

0.4.0 (2026-06-23)

Full Changelog: v0.3.0...v0.4.0

Features

• api: add files resource, file_id support in image refs (4fd928a)
• api: add keyframe_indexes and keyframes fields to video_options (f8d3c16)

---

This pull request is managed by Stainless's GitHub App.

The semver version number is based on included commit messages. Alternatively, you can manually set the version number in the title of this pull request.

For a better experience, it is recommended to use either rebase-merge or squash-merge when merging this pull request.

🔗 Stainless website
📚 Read the docs
🙋 Reach out for help or questions

[cursor]

PR Summary

Low Risk
Additive, OpenAPI-generated client changes with new optional fields; no auth or breaking signature changes to existing generation calls.

Overview
Release 0.4.0 bumps the package and OpenAPI-backed SDK to match expanded Luma Agents API coverage (endpoint count 2 → 7).

Adds a client.files resource (sync/async, raw/streaming wrappers) with create (inline multipart or presigned JSON + complete), list, get, and delete, plus typed models for file lifecycle, purpose, and presigned upload envelopes.

Generations gain file_id on ImageRefParam (and related docs) so source, image_ref, and video frame refs can point at uploaded files instead of only URL, base64, or generation_id.

Video request types add top-level video.keyframes / video.keyframe_indexes for ray-3.2 image-to-video anchoring, extend VideoResolution with 360p, and refresh option docs (e.g. video_edit source length, 360p constraints). api.md, changelog, and API resource tests reflect the new surface.

^{Reviewed by Cursor Bugbot for commit 68e2652. Bugbot is set up for automated code reviews on this repo. Configure here.}

[stainless-app]

🧪 Testing

To try out this version of the SDK:

pip install 'https://pkg.stainless.com/s/luma-agents-python/4fd928ab82faab241fc18ddcce86b7f76a02d288/luma_agents-0.3.0-py3-none-any.whl'

Expires at: Thu, 23 Jul 2026 18:09:32 GMT
Updated at: Tue, 23 Jun 2026 18:09:32 GMT

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Inline upload missing file parameter
  • Added the typed file parameter to sync and async file creation and included it in the request body so existing multipart extraction can send inline uploads.

Or push these changes by commenting:

@cursor push a12851bf5a

Preview (a12851bf5a)

diff --git a/src/luma_agents/resources/files.py b/src/luma_agents/resources/files.py
--- a/src/luma_agents/resources/files.py
+++ b/src/luma_agents/resources/files.py
@@ -9,7 +9,7 @@
 
 from ..types import FileState, FilePurpose, file_list_params, file_create_params
 from .._files import deepcopy_with_paths
-from .._types import Body, Omit, Query, Headers, NoneType, NotGiven, omit, not_given
+from .._types import Body, Omit, Query, Headers, NoneType, NotGiven, FileTypes, omit, not_given
 from .._utils import extract_files, path_template, maybe_transform, async_maybe_transform
 from .._compat import cached_property
 from .._resource import SyncAPIResource, AsyncAPIResource
@@ -55,6 +55,7 @@
         mime_type: str,
         size_bytes: int,
         expires_at: Union[str, datetime, None] | Omit = omit,
+        file: FileTypes | Omit = omit,
         filename: Optional[str] | Omit = omit,
         purpose: FilePurpose | Omit = omit,
         user_id: Optional[str] | Omit = omit,
@@ -87,6 +88,8 @@
           expires_at: Optional TTL. After this time Luma may automatically delete the file and reclaim
               its bytes.
 
+          file: File to upload inline using multipart/form-data.
+
           filename: Optional original filename to record.
 
           purpose: How the file is intended to be used in a generation. `input` is the primary
@@ -109,6 +112,7 @@
                 "mime_type": mime_type,
                 "size_bytes": size_bytes,
                 "expires_at": expires_at,
+                "file": file,
                 "filename": filename,
                 "purpose": purpose,
                 "user_id": user_id,
@@ -319,6 +323,7 @@
         mime_type: str,
         size_bytes: int,
         expires_at: Union[str, datetime, None] | Omit = omit,
+        file: FileTypes | Omit = omit,
         filename: Optional[str] | Omit = omit,
         purpose: FilePurpose | Omit = omit,
         user_id: Optional[str] | Omit = omit,
@@ -351,6 +356,8 @@
           expires_at: Optional TTL. After this time Luma may automatically delete the file and reclaim
               its bytes.
 
+          file: File to upload inline using multipart/form-data.
+
           filename: Optional original filename to record.
 
           purpose: How the file is intended to be used in a generation. `input` is the primary
@@ -373,6 +380,7 @@
                 "mime_type": mime_type,
                 "size_bytes": size_bytes,
                 "expires_at": expires_at,
+                "file": file,
                 "filename": filename,
                 "purpose": purpose,
                 "user_id": user_id,

diff --git a/src/luma_agents/types/file_create_params.py b/src/luma_agents/types/file_create_params.py
--- a/src/luma_agents/types/file_create_params.py
+++ b/src/luma_agents/types/file_create_params.py
@@ -6,6 +6,7 @@
 from datetime import datetime
 from typing_extensions import Required, Annotated, TypedDict
 
+from .._types import FileTypes
 from .._utils import PropertyInfo
 from .file_purpose import FilePurpose
 
@@ -28,6 +29,9 @@
     After this time Luma may automatically delete the file and reclaim its bytes.
     """
 
+    file: FileTypes
+    """File to upload inline using multipart/form-data."""
+
     filename: Optional[str]
     """Optional original filename to record."""

_{You can send follow-ups to the cloud agent here.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 68e2652. Configure here.}

[stainless-app]

🤖 Release is at https://github.com/lumalabs/luma-agents-python/releases/tag/v0.4.0 🌻