temporary: RemoteComboOptions widget examples

comfy_api/latest/_io.py

@@ -43,7 +43,67 @@ class UploadType(str, Enum):
     model = "file_upload"
 
 
+class RemoteItemSchema:
+    """Describes how to map API response objects to rich dropdown items.
+
+    All *_field parameters use dot-path notation (e.g. ``"labels.gender"``).
+    ``label_field`` and ``description_field`` additionally support template strings
+    with ``{field}`` placeholders (e.g. ``"{name} ({labels.accent})"``).
+    """
+    def __init__(
+        self,
+        value_field: str,
+        label_field: str,
+        preview_url_field: str | None = None,
+        preview_type: Literal["image", "video", "audio"] = "image",
+        description_field: str | None = None,
+        search_fields: list[str] | None = None,
+    ):
+        if preview_type not in ("image", "video", "audio"):
+            raise ValueError(
+                f"RemoteItemSchema: 'preview_type' must be 'image', 'video', or 'audio'; got {preview_type!r}."
+            )
+        if search_fields is not None:
+            for f in search_fields:
+                if "{" in f or "}" in f:
+                    raise ValueError(
+                        f"RemoteItemSchema: 'search_fields' must be dot-paths, not template strings (got {f!r})."
+                    )
+        self.value_field = value_field
+        """Dot-path to the unique identifier within each item.
+        This value is stored in the widget and passed to execute()."""
+        self.label_field = label_field
+        """Dot-path to the display name, or a template string with {field} placeholders."""
+        self.preview_url_field = preview_url_field
+        """Dot-path to a preview media URL. If None, no preview is shown."""
+        self.preview_type = preview_type
+        """How to render the preview: "image", "video", or "audio"."""
+        self.description_field = description_field
+        """Optional dot-path or template for a subtitle line shown below the label."""
+        self.search_fields = search_fields
+        """Dot-paths to fields included in the search index. When unset, search falls back to
+        the resolved label (i.e. ``label_field`` after template substitution). Note that template
+        label strings (e.g. ``"{first} {last}"``) are not valid path entries here — list the
+        underlying paths (``["first", "last"]``) instead."""
+
+    def as_dict(self):
+        return prune_dict({
+            "value_field": self.value_field,
+            "label_field": self.label_field,
+            "preview_url_field": self.preview_url_field,
+            "preview_type": self.preview_type,
+            "description_field": self.description_field,
+            "search_fields": self.search_fields,
+        })
+
+
 class RemoteOptions:
+    """Plain remote combo: fetches a list of strings/objects and populates a standard dropdown.
+
+    Use this for lightweight lists from endpoints that return a bare array (or an array under
+    ``response_key``). For rich dropdowns with previews, search, filtering, or pagination,
+    use :class:`RemoteComboOptions` and the ``remote_combo=`` parameter on ``Combo.Input``.
+    """
     def __init__(self, route: str, refresh_button: bool, control_after_refresh: Literal["first", "last"]="first",
                  timeout: int=None, max_retries: int=None, refresh: int=None):
         self.route = route
@@ -70,6 +130,80 @@ def as_dict(self):
         })
 
 
+class RemoteComboOptions:
+    """Rich remote combo: populates a Vue dropdown with previews, search, and filtering.
+
+    Attached to a :class:`Combo.Input` via ``remote_combo=`` (not ``remote=``). Requires an
+    ``item_schema`` describing how to map API response objects to dropdown items.
+
+    Response-shape contract: the endpoint returns the full items array in a single response
+    (either at the top level, or at the dot-path given by ``response_key``). Backing endpoints
+    that paginate upstream are expected to aggregate and cache server-side.
+    """
+    def __init__(
+        self,
+        route: str,
+        item_schema: RemoteItemSchema,
+        refresh_button: bool = True,
+        auto_select: Literal["first", "last"] | None = None,
+        timeout: int | None = None,
+        max_retries: int | None = None,
+        refresh: int | None = None,
+        response_key: str | None = None,
+    ):
+        if auto_select is not None and auto_select not in ("first", "last"):
+            raise ValueError(
+                f"RemoteComboOptions: 'auto_select' must be 'first', 'last', or None; got {auto_select!r}."
+            )
+        if refresh is not None and 0 < refresh < 128:
+            raise ValueError(
+                f"RemoteComboOptions: 'refresh' must be >= 128 (ms TTL) or <= 0 (cache never expires); got {refresh}."
+            )
+        if timeout is not None and timeout < 0:
+            raise ValueError(
+                f"RemoteComboOptions: 'timeout' must be >= 0 (got {timeout})."
+            )
+        if max_retries is not None and max_retries < 0:
+            raise ValueError(
+                f"RemoteComboOptions: 'max_retries' must be >= 0 (got {max_retries})."
+            )
+        if not route.startswith("/"):
+            raise ValueError(
+                f"RemoteComboOptions: 'route' must be a relative path starting with '/'; got {route!r}."
+            )
+        self.route = route
+        """Relative path to the remote source (must start with ``/``). The frontend resolves this
+        against the comfy-api base URL and injects auth headers; absolute URLs are rejected."""
+        self.item_schema = item_schema
+        """Required: describes how each API response object maps to a dropdown item."""
+        self.refresh_button = refresh_button
+        """Specifies whether to show a refresh button next to the widget."""
+        self.auto_select = auto_select
+        """Fallback item to select when the widget's value is empty. Never overrides an existing
+        selection. Default None means no fallback."""
+        self.timeout = timeout
+        """Maximum time to wait for a response, in milliseconds."""
+        self.max_retries = max_retries
+        """Maximum number of retries before aborting the request. Default None uses the frontend's built-in limit."""
+        self.refresh = refresh
+        """TTL of the cached value in milliseconds. Must be >= 128 (ms TTL) or <= 0 (cache never expires,
+        re-fetched only via the refresh button). Default None uses the frontend's built-in behavior."""
+        self.response_key = response_key
+        """Dot-path to the items array within the response (when not at the top level)."""
+
+    def as_dict(self):
+        return prune_dict({
+            "route": self.route,
+            "item_schema": self.item_schema.as_dict(),
+            "refresh_button": self.refresh_button,
+            "auto_select": self.auto_select,
+            "timeout": self.timeout,
+            "max_retries": self.max_retries,
+            "refresh": self.refresh,
+            "response_key": self.response_key,
+        })
+
+
 class NumberDisplay(str, Enum):
     number = "number"
     slider = "slider"
@@ -359,11 +493,16 @@ def __init__(
             upload: UploadType=None,
             image_folder: FolderType=None,
             remote: RemoteOptions=None,
+            remote_combo: RemoteComboOptions=None,
             socketless: bool=None,
             extra_dict=None,
             raw_link: bool=None,
             advanced: bool=None,
         ):
+            if remote is not None and remote_combo is not None:
+                raise ValueError("Combo.Input: pass either 'remote' or 'remote_combo', not both.")
+            if options is not None and remote_combo is not None:
+                raise ValueError("Combo.Input: pass either 'options' or 'remote_combo', not both.")
             if isinstance(options, type) and issubclass(options, Enum):
                 options = [v.value for v in options]
             if isinstance(default, Enum):
@@ -375,6 +514,7 @@ def __init__(
             self.upload = upload
             self.image_folder = image_folder
             self.remote = remote
+            self.remote_combo = remote_combo
             self.default: str
 
         def as_dict(self):
@@ -385,6 +525,7 @@ def as_dict(self):
                 **({self.upload.value: True} if self.upload is not None else {}),
                 "image_folder": self.image_folder.value if self.image_folder else None,
                 "remote": self.remote.as_dict() if self.remote else None,
+                "remote_combo": self.remote_combo.as_dict() if self.remote_combo else None,
             })
 
     class Output(Output):
@@ -2221,7 +2362,9 @@ def as_dict(self):
 __all__ = [
     "FolderType",
     "UploadType",
+    "RemoteItemSchema",
     "RemoteOptions",
+    "RemoteComboOptions",
     "NumberDisplay",
     "ControlAfterGenerate",
 

comfy_api_nodes/apis/bytedance.py

@@ -132,6 +132,10 @@ class GetAssetResponse(BaseModel):
     error: TaskStatusError | None = Field(None)
 
 
+class SeedanceCreateVisualValidateSessionRequest(BaseModel):
+    name: str | None = Field(None, max_length=64)
+
+
 class SeedanceCreateVisualValidateSessionResponse(BaseModel):
     session_id: str = Field(...)
     h5_link: str = Field(...)
@@ -141,6 +145,7 @@ class SeedanceGetVisualValidateSessionResponse(BaseModel):
     session_id: str = Field(...)
     status: str = Field(...)
     group_id: str | None = Field(None)
+    name: str | None = Field(None)
     error_code: str | None = Field(None)
     error_message: str | None = Field(None)