From d3c18c163665a6f94e7dc56823aabcb93ebf7e5e Mon Sep 17 00:00:00 2001
From: "Yousef R. Gamaleldin" <81116377+yousef-rafat@users.noreply.github.com>
Date: Fri, 8 May 2026 12:59:24 +0300
Subject: [PATCH 01/10] Add support for BiRefNet background remove model
 (CORE-46) (#12747)

---
 comfy/background_removal/birefnet.json        |   7 +
 comfy/background_removal/birefnet.py          | 689 ++++++++++++++++++
 comfy/bg_removal_model.py                     |  78 ++
 comfy/ops.py                                  |  22 +
 comfy_api/latest/_io.py                       |   7 +
 comfy_extras/nodes_bg_removal.py              |  60 ++
 comfy_extras/nodes_mask.py                    |  27 +-
 folder_paths.py                               |   2 +
 .../put_background_removal_models_here        |   0
 nodes.py                                      |   1 +
 10 files changed, 887 insertions(+), 6 deletions(-)
 create mode 100644 comfy/background_removal/birefnet.json
 create mode 100644 comfy/background_removal/birefnet.py
 create mode 100644 comfy/bg_removal_model.py
 create mode 100644 comfy_extras/nodes_bg_removal.py
 create mode 100644 models/background_removal/put_background_removal_models_here

diff --git a/comfy/background_removal/birefnet.json b/comfy/background_removal/birefnet.json
new file mode 100644
index 000000000..f0960af39
--- /dev/null
+++ b/comfy/background_removal/birefnet.json
@@ -0,0 +1,7 @@
+{
+    "model_type": "birefnet",
+    "image_std": [1.0, 1.0, 1.0],
+    "image_mean": [0.0, 0.0, 0.0],
+    "image_size": 1024,
+    "resize_to_original": true
+}
diff --git a/comfy/background_removal/birefnet.py b/comfy/background_removal/birefnet.py
new file mode 100644
index 000000000..df54b2b90
--- /dev/null
+++ b/comfy/background_removal/birefnet.py
@@ -0,0 +1,689 @@
+import torch
+import comfy.ops
+import numpy as np
+import torch.nn as nn
+from functools import partial
+import torch.nn.functional as F
+from torchvision.ops import deform_conv2d
+from comfy.ldm.modules.attention import optimized_attention_for_device
+
+CXT = [3072, 1536, 768, 384][1:][::-1][-3:]
+
+class Attention(nn.Module):
+    def __init__(self, dim, num_heads=8, qkv_bias=False, qk_scale=None, device=None, dtype=None, operations=None):
+        super().__init__()
+
+        self.dim = dim
+        self.num_heads = num_heads
+        head_dim = dim // num_heads
+        self.scale = qk_scale or head_dim ** -0.5
+
+        self.q = operations.Linear(dim, dim, bias=qkv_bias, device=device, dtype=dtype)
+        self.kv = operations.Linear(dim, dim * 2, bias=qkv_bias, device=device, dtype=dtype)
+        self.proj = operations.Linear(dim, dim, device=device, dtype=dtype)
+
+    def forward(self, x):
+        B, N, C = x.shape
+        optimized_attention = optimized_attention_for_device(x.device, mask=False, small_input=True)
+        q = self.q(x).reshape(B, N, self.num_heads, C // self.num_heads).permute(0, 2, 1, 3)
+        kv = self.kv(x).reshape(B, -1, 2, self.num_heads, C // self.num_heads).permute(2, 0, 3, 1, 4)
+        k, v = kv[0], kv[1]
+
+        x = optimized_attention(
+            q, k, v, heads=self.num_heads, skip_output_reshape=True, skip_reshape=True
+        ).transpose(1, 2).reshape(B, N, C)
+        x = self.proj(x)
+
+        return x
+
+class Mlp(nn.Module):
+    def __init__(self, in_features, hidden_features=None, out_features=None, device=None, dtype=None, operations=None):
+        super().__init__()
+        out_features = out_features or in_features
+        hidden_features = hidden_features or in_features
+        self.fc1 = operations.Linear(in_features, hidden_features, device=device, dtype=dtype)
+        self.act = nn.GELU()
+        self.fc2 = operations.Linear(hidden_features, out_features, device=device, dtype=dtype)
+
+    def forward(self, x):
+        x = self.fc1(x)
+        x = self.act(x)
+        x = self.fc2(x)
+        return x
+
+
+def window_partition(x, window_size):
+    B, H, W, C = x.shape
+    x = x.view(B, H // window_size, window_size, W // window_size, window_size, C)
+    windows = x.permute(0, 1, 3, 2, 4, 5).contiguous().view(-1, window_size, window_size, C)
+    return windows
+
+
+def window_reverse(windows, window_size, H, W):
+    B = int(windows.shape[0] / (H * W / window_size / window_size))
+    x = windows.view(B, H // window_size, W // window_size, window_size, window_size, -1)
+    x = x.permute(0, 1, 3, 2, 4, 5).contiguous().view(B, H, W, -1)
+    return x
+
+
+class WindowAttention(nn.Module):
+    def __init__(self, dim, window_size, num_heads, qkv_bias=True, qk_scale=None, device=None, dtype=None, operations=None):
+
+        super().__init__()
+        self.dim = dim
+        self.window_size = window_size  # Wh, Ww
+        self.num_heads = num_heads
+        head_dim = dim // num_heads
+        self.scale = qk_scale or head_dim ** -0.5
+
+        self.relative_position_bias_table = nn.Parameter(
+            torch.zeros((2 * window_size[0] - 1) * (2 * window_size[1] - 1), num_heads, device=device, dtype=dtype))
+
+        coords_h = torch.arange(self.window_size[0])
+        coords_w = torch.arange(self.window_size[1])
+        coords = torch.stack(torch.meshgrid([coords_h, coords_w], indexing='ij'))  # 2, Wh, Ww
+        coords_flatten = torch.flatten(coords, 1)  # 2, Wh*Ww
+        relative_coords = coords_flatten[:, :, None] - coords_flatten[:, None, :]  # 2, Wh*Ww, Wh*Ww
+        relative_coords = relative_coords.permute(1, 2, 0).contiguous()  # Wh*Ww, Wh*Ww, 2
+        relative_coords[:, :, 0] += self.window_size[0] - 1
+        relative_coords[:, :, 1] += self.window_size[1] - 1
+        relative_coords[:, :, 0] *= 2 * self.window_size[1] - 1
+        relative_position_index = relative_coords.sum(-1)  # Wh*Ww, Wh*Ww
+        self.register_buffer("relative_position_index", relative_position_index)
+
+        self.qkv = operations.Linear(dim, dim * 3, bias=qkv_bias, device=device, dtype=dtype)
+        self.proj = operations.Linear(dim, dim, device=device, dtype=dtype)
+        self.softmax = nn.Softmax(dim=-1)
+
+    def forward(self, x, mask=None):
+        B_, N, C = x.shape
+        qkv = self.qkv(x).reshape(B_, N, 3, self.num_heads, C // self.num_heads).permute(2, 0, 3, 1, 4)
+        q, k, v = qkv[0], qkv[1], qkv[2]
+
+        q = q * self.scale
+        attn = (q @ k.transpose(-2, -1))
+
+        relative_position_bias = self.relative_position_bias_table[self.relative_position_index.long().view(-1)].view(
+            self.window_size[0] * self.window_size[1], self.window_size[0] * self.window_size[1], -1)  # Wh*Ww,Wh*Ww,nH
+        relative_position_bias = relative_position_bias.permute(2, 0, 1).contiguous()  # nH, Wh*Ww, Wh*Ww
+        attn = attn + relative_position_bias.unsqueeze(0)
+
+        if mask is not None:
+            nW = mask.shape[0]
+            attn = attn.view(B_ // nW, nW, self.num_heads, N, N) + mask.unsqueeze(1).unsqueeze(0)
+            attn = attn.view(-1, self.num_heads, N, N)
+            attn = self.softmax(attn)
+        else:
+            attn = self.softmax(attn)
+
+        x = (attn @ v).transpose(1, 2).reshape(B_, N, C)
+        x = self.proj(x)
+        return x
+
+
+class SwinTransformerBlock(nn.Module):
+    def __init__(self, dim, num_heads, window_size=7, shift_size=0,
+                 mlp_ratio=4., qkv_bias=True, qk_scale=None,
+                 norm_layer=nn.LayerNorm, device=None, dtype=None, operations=None):
+        super().__init__()
+        self.dim = dim
+        self.num_heads = num_heads
+        self.window_size = window_size
+        self.shift_size = shift_size
+        self.mlp_ratio = mlp_ratio
+
+        self.norm1 = norm_layer(dim, device=device, dtype=dtype)
+        self.attn = WindowAttention(
+            dim, window_size=(self.window_size, self.window_size), num_heads=num_heads,
+            qkv_bias=qkv_bias, qk_scale=qk_scale, device=device, dtype=dtype, operations=operations)
+
+        self.norm2 = norm_layer(dim, device=device, dtype=dtype)
+        mlp_hidden_dim = int(dim * mlp_ratio)
+        self.mlp = Mlp(in_features=dim, hidden_features=mlp_hidden_dim, device=device, dtype=dtype, operations=operations)
+
+        self.H = None
+        self.W = None
+
+    def forward(self, x, mask_matrix):
+        B, L, C = x.shape
+        H, W = self.H, self.W
+
+        shortcut = x
+        x = self.norm1(x)
+        x = x.view(B, H, W, C)
+
+        pad_l = pad_t = 0
+        pad_r = (self.window_size - W % self.window_size) % self.window_size
+        pad_b = (self.window_size - H % self.window_size) % self.window_size
+        x = F.pad(x, (0, 0, pad_l, pad_r, pad_t, pad_b))
+        _, Hp, Wp, _ = x.shape
+
+        if self.shift_size > 0:
+            shifted_x = torch.roll(x, shifts=(-self.shift_size, -self.shift_size), dims=(1, 2))
+            attn_mask = mask_matrix
+        else:
+            shifted_x = x
+            attn_mask = None
+
+        x_windows = window_partition(shifted_x, self.window_size)
+        x_windows = x_windows.view(-1, self.window_size * self.window_size, C)
+
+        attn_windows = self.attn(x_windows, mask=attn_mask)
+
+        attn_windows = attn_windows.view(-1, self.window_size, self.window_size, C)
+        shifted_x = window_reverse(attn_windows, self.window_size, Hp, Wp)  # B H' W' C
+
+        if self.shift_size > 0:
+            x = torch.roll(shifted_x, shifts=(self.shift_size, self.shift_size), dims=(1, 2))
+        else:
+            x = shifted_x
+
+        if pad_r > 0 or pad_b > 0:
+            x = x[:, :H, :W, :].contiguous()
+
+        x = x.view(B, H * W, C)
+
+        x = shortcut + x
+        x = x + self.mlp(self.norm2(x))
+
+        return x
+
+
+class PatchMerging(nn.Module):
+    def __init__(self, dim, device=None, dtype=None, operations=None):
+        super().__init__()
+        self.dim = dim
+        self.reduction = operations.Linear(4 * dim, 2 * dim, bias=False, device=device, dtype=dtype)
+        self.norm = operations.LayerNorm(4 * dim, device=device, dtype=dtype)
+
+    def forward(self, x, H, W):
+        B, L, C = x.shape
+        x = x.view(B, H, W, C)
+
+        # padding
+        pad_input = (H % 2 == 1) or (W % 2 == 1)
+        if pad_input:
+            x = F.pad(x, (0, 0, 0, W % 2, 0, H % 2))
+
+        x0 = x[:, 0::2, 0::2, :]  # B H/2 W/2 C
+        x1 = x[:, 1::2, 0::2, :]  # B H/2 W/2 C
+        x2 = x[:, 0::2, 1::2, :]  # B H/2 W/2 C
+        x3 = x[:, 1::2, 1::2, :]  # B H/2 W/2 C
+        x = torch.cat([x0, x1, x2, x3], -1)  # B H/2 W/2 4*C
+        x = x.view(B, -1, 4 * C)  # B H/2*W/2 4*C
+
+        x = self.norm(x)
+        x = self.reduction(x)
+
+        return x
+
+
+class BasicLayer(nn.Module):
+    def __init__(self,
+                 dim,
+                 depth,
+                 num_heads,
+                 window_size=7,
+                 mlp_ratio=4.,
+                 qkv_bias=True,
+                 qk_scale=None,
+                 norm_layer=nn.LayerNorm,
+                 downsample=None,
+                 device=None, dtype=None, operations=None):
+        super().__init__()
+        self.window_size = window_size
+        self.shift_size = window_size // 2
+        self.depth = depth
+
+        # build blocks
+        self.blocks = nn.ModuleList([
+            SwinTransformerBlock(
+                dim=dim,
+                num_heads=num_heads,
+                window_size=window_size,
+                shift_size=0 if (i % 2 == 0) else window_size // 2,
+                mlp_ratio=mlp_ratio,
+                qkv_bias=qkv_bias,
+                qk_scale=qk_scale,
+                norm_layer=norm_layer,
+                device=device, dtype=dtype, operations=operations)
+            for i in range(depth)])
+
+        # patch merging layer
+        if downsample is not None:
+            self.downsample = downsample(dim=dim, device=device, dtype=dtype, operations=operations)
+        else:
+            self.downsample = None
+
+    def forward(self, x, H, W):
+        Hp = int(np.ceil(H / self.window_size)) * self.window_size
+        Wp = int(np.ceil(W / self.window_size)) * self.window_size
+        img_mask = torch.zeros((1, Hp, Wp, 1), device=x.device)  # 1 Hp Wp 1
+        h_slices = (slice(0, -self.window_size),
+                    slice(-self.window_size, -self.shift_size),
+                    slice(-self.shift_size, None))
+        w_slices = (slice(0, -self.window_size),
+                    slice(-self.window_size, -self.shift_size),
+                    slice(-self.shift_size, None))
+        cnt = 0
+        for h in h_slices:
+            for w in w_slices:
+                img_mask[:, h, w, :] = cnt
+                cnt += 1
+
+        mask_windows = window_partition(img_mask, self.window_size)
+        mask_windows = mask_windows.view(-1, self.window_size * self.window_size)
+        attn_mask = mask_windows.unsqueeze(1) - mask_windows.unsqueeze(2)
+        attn_mask = attn_mask.masked_fill(attn_mask != 0, float(-100.0)).masked_fill(attn_mask == 0, float(0.0))
+
+        for blk in self.blocks:
+            blk.H, blk.W = H, W
+            x = blk(x, attn_mask)
+        if self.downsample is not None:
+            x_down = self.downsample(x, H, W)
+            Wh, Ww = (H + 1) // 2, (W + 1) // 2
+            return x, H, W, x_down, Wh, Ww
+        else:
+            return x, H, W, x, H, W
+
+
+class PatchEmbed(nn.Module):
+    def __init__(self, patch_size=4, in_channels=3, embed_dim=96, norm_layer=None, device=None, dtype=None, operations=None):
+        super().__init__()
+        patch_size = (patch_size, patch_size)
+        self.patch_size = patch_size
+
+        self.in_channels = in_channels
+        self.embed_dim = embed_dim
+
+        self.proj = operations.Conv2d(in_channels, embed_dim, kernel_size=patch_size, stride=patch_size, device=device, dtype=dtype)
+        if norm_layer is not None:
+            self.norm = norm_layer(embed_dim, device=device, dtype=dtype)
+        else:
+            self.norm = None
+
+    def forward(self, x):
+        _, _, H, W = x.size()
+        if W % self.patch_size[1] != 0:
+            x = F.pad(x, (0, self.patch_size[1] - W % self.patch_size[1]))
+        if H % self.patch_size[0] != 0:
+            x = F.pad(x, (0, 0, 0, self.patch_size[0] - H % self.patch_size[0]))
+
+        x = self.proj(x)  # B C Wh Ww
+        if self.norm is not None:
+            Wh, Ww = x.size(2), x.size(3)
+            x = x.flatten(2).transpose(1, 2)
+            x = self.norm(x)
+            x = x.transpose(1, 2).view(-1, self.embed_dim, Wh, Ww)
+
+        return x
+
+
+class SwinTransformer(nn.Module):
+    def __init__(self,
+                 pretrain_img_size=224,
+                 patch_size=4,
+                 in_channels=3,
+                 embed_dim=96,
+                 depths=[2, 2, 6, 2],
+                 num_heads=[3, 6, 12, 24],
+                 window_size=7,
+                 mlp_ratio=4.,
+                 qkv_bias=True,
+                 qk_scale=None,
+                 patch_norm=True,
+                 out_indices=(0, 1, 2, 3),
+                 frozen_stages=-1,
+                 device=None, dtype=None, operations=None):
+        super().__init__()
+
+        norm_layer = partial(operations.LayerNorm, device=device, dtype=dtype)
+        self.pretrain_img_size = pretrain_img_size
+        self.num_layers = len(depths)
+        self.embed_dim = embed_dim
+        self.patch_norm = patch_norm
+        self.out_indices = out_indices
+        self.frozen_stages = frozen_stages
+
+        self.patch_embed = PatchEmbed(
+            patch_size=patch_size, in_channels=in_channels, embed_dim=embed_dim,
+            device=device, dtype=dtype, operations=operations,
+            norm_layer=norm_layer if self.patch_norm else None)
+
+        self.layers = nn.ModuleList()
+        for i_layer in range(self.num_layers):
+            layer = BasicLayer(
+                dim=int(embed_dim * 2 ** i_layer),
+                depth=depths[i_layer],
+                num_heads=num_heads[i_layer],
+                window_size=window_size,
+                mlp_ratio=mlp_ratio,
+                qkv_bias=qkv_bias,
+                qk_scale=qk_scale,
+                norm_layer=norm_layer,
+                downsample=PatchMerging if (i_layer < self.num_layers - 1) else None,
+                device=device, dtype=dtype, operations=operations)
+            self.layers.append(layer)
+
+        num_features = [int(embed_dim * 2 ** i) for i in range(self.num_layers)]
+        self.num_features = num_features
+
+        for i_layer in out_indices:
+            layer = norm_layer(num_features[i_layer])
+            layer_name = f'norm{i_layer}'
+            self.add_module(layer_name, layer)
+
+
+    def forward(self, x):
+        x = self.patch_embed(x)
+
+        Wh, Ww = x.size(2), x.size(3)
+
+        outs = []
+        x = x.flatten(2).transpose(1, 2)
+        for i in range(self.num_layers):
+            layer = self.layers[i]
+            x_out, H, W, x, Wh, Ww = layer(x, Wh, Ww)
+
+            if i in self.out_indices:
+                norm_layer = getattr(self, f'norm{i}')
+                x_out = norm_layer(x_out)
+
+                out = x_out.view(-1, H, W, self.num_features[i]).permute(0, 3, 1, 2).contiguous()
+                outs.append(out)
+
+        return tuple(outs)
+
+class DeformableConv2d(nn.Module):
+    def __init__(self,
+                 in_channels,
+                 out_channels,
+                 kernel_size=3,
+                 stride=1,
+                 padding=1,
+                 bias=False, device=None, dtype=None, operations=None):
+
+        super(DeformableConv2d, self).__init__()
+
+        kernel_size = kernel_size if type(kernel_size) is tuple else (kernel_size, kernel_size)
+        self.stride = stride if type(stride) is tuple else (stride, stride)
+        self.padding = padding
+
+        self.offset_conv = operations.Conv2d(in_channels,
+                                     2 * kernel_size[0] * kernel_size[1],
+                                     kernel_size=kernel_size,
+                                     stride=stride,
+                                     padding=self.padding,
+                                     bias=True, device=device, dtype=dtype)
+
+        self.modulator_conv = operations.Conv2d(in_channels,
+                                     1 * kernel_size[0] * kernel_size[1],
+                                     kernel_size=kernel_size,
+                                     stride=stride,
+                                     padding=self.padding,
+                                     bias=True, device=device, dtype=dtype)
+
+        self.regular_conv = operations.Conv2d(in_channels,
+                                      out_channels=out_channels,
+                                      kernel_size=kernel_size,
+                                      stride=stride,
+                                      padding=self.padding,
+                                      bias=bias, device=device, dtype=dtype)
+
+    def forward(self, x):
+        offset = self.offset_conv(x)
+        modulator = 2. * torch.sigmoid(self.modulator_conv(x))
+        weight, bias, offload_info = comfy.ops.cast_bias_weight(self.regular_conv, x, offloadable=True)
+
+        x = deform_conv2d(
+            input=x,
+            offset=offset,
+            weight=weight,
+            bias=None,
+            padding=self.padding,
+            mask=modulator,
+            stride=self.stride,
+        )
+        comfy.ops.uncast_bias_weight(self.regular_conv, weight, bias, offload_info)
+        return x
+
+class BasicDecBlk(nn.Module):
+    def __init__(self, in_channels=64, out_channels=64, inter_channels=64, device=None, dtype=None, operations=None):
+        super(BasicDecBlk, self).__init__()
+        inter_channels = 64
+        self.conv_in = operations.Conv2d(in_channels, inter_channels, 3, 1, padding=1, device=device, dtype=dtype)
+        self.relu_in = nn.ReLU(inplace=True)
+        self.dec_att = ASPPDeformable(in_channels=inter_channels, device=device, dtype=dtype, operations=operations)
+        self.conv_out = operations.Conv2d(inter_channels, out_channels, 3, 1, padding=1, device=device, dtype=dtype)
+        self.bn_in = operations.BatchNorm2d(inter_channels, device=device, dtype=dtype)
+        self.bn_out = operations.BatchNorm2d(out_channels, device=device, dtype=dtype)
+
+    def forward(self, x):
+        x = self.conv_in(x)
+        x = self.bn_in(x)
+        x = self.relu_in(x)
+        x = self.dec_att(x)
+        x = self.conv_out(x)
+        x = self.bn_out(x)
+        return x
+
+
+class BasicLatBlk(nn.Module):
+    def __init__(self, in_channels=64, out_channels=64, device=None, dtype=None, operations=None):
+        super(BasicLatBlk, self).__init__()
+        self.conv = operations.Conv2d(in_channels, out_channels, 1, 1, 0, device=device, dtype=dtype)
+
+    def forward(self, x):
+        x = self.conv(x)
+        return x
+
+
+class _ASPPModuleDeformable(nn.Module):
+    def __init__(self, in_channels, planes, kernel_size, padding, device, dtype, operations):
+        super(_ASPPModuleDeformable, self).__init__()
+        self.atrous_conv = DeformableConv2d(in_channels, planes, kernel_size=kernel_size,
+                                            stride=1, padding=padding, bias=False, device=device, dtype=dtype, operations=operations)
+        self.bn = operations.BatchNorm2d(planes, device=device, dtype=dtype)
+        self.relu = nn.ReLU(inplace=True)
+
+    def forward(self, x):
+        x = self.atrous_conv(x)
+        x = self.bn(x)
+
+        return self.relu(x)
+
+
+class ASPPDeformable(nn.Module):
+    def __init__(self, in_channels, out_channels=None, parallel_block_sizes=[1, 3, 7], device=None, dtype=None, operations=None):
+        super(ASPPDeformable, self).__init__()
+        self.down_scale = 1
+        if out_channels is None:
+            out_channels = in_channels
+        self.in_channelster = 256 // self.down_scale
+
+        self.aspp1 = _ASPPModuleDeformable(in_channels, self.in_channelster, 1, padding=0, device=device, dtype=dtype, operations=operations)
+        self.aspp_deforms = nn.ModuleList([
+            _ASPPModuleDeformable(in_channels, self.in_channelster, conv_size, padding=int(conv_size//2), device=device, dtype=dtype, operations=operations)
+              for conv_size in parallel_block_sizes
+        ])
+
+        self.global_avg_pool = nn.Sequential(nn.AdaptiveAvgPool2d((1, 1)),
+                                             operations.Conv2d(in_channels, self.in_channelster, 1, stride=1, bias=False, device=device, dtype=dtype),
+                                             operations.BatchNorm2d(self.in_channelster, device=device, dtype=dtype),
+                                             nn.ReLU(inplace=True))
+        self.conv1 = operations.Conv2d(self.in_channelster * (2 + len(self.aspp_deforms)), out_channels, 1, bias=False, device=device, dtype=dtype)
+        self.bn1 = operations.BatchNorm2d(out_channels, device=device, dtype=dtype)
+        self.relu = nn.ReLU(inplace=True)
+
+    def forward(self, x):
+        x1 = self.aspp1(x)
+        x_aspp_deforms = [aspp_deform(x) for aspp_deform in self.aspp_deforms]
+        x5 = self.global_avg_pool(x)
+        x5 = F.interpolate(x5, size=x1.size()[2:], mode='bilinear', align_corners=True)
+        x = torch.cat((x1, *x_aspp_deforms, x5), dim=1)
+
+        x = self.conv1(x)
+        x = self.bn1(x)
+        x = self.relu(x)
+
+        return x
+
+class BiRefNet(nn.Module):
+    def __init__(self, config=None, dtype=None, device=None, operations=None):
+        super(BiRefNet, self).__init__()
+        self.bb = SwinTransformer(embed_dim=192, depths=[2, 2, 18, 2], num_heads=[6, 12, 24, 48], window_size=12, device=device, dtype=dtype, operations=operations)
+
+        channels = [1536, 768, 384, 192]
+        channels = [c * 2 for c in channels]
+        self.cxt = channels[1:][::-1][-3:]
+        self.squeeze_module = nn.Sequential(*[
+            BasicDecBlk(channels[0]+sum(self.cxt), channels[0], device=device, dtype=dtype, operations=operations)
+            for _ in range(1)
+        ])
+
+        self.decoder = Decoder(channels, device=device, dtype=dtype, operations=operations)
+
+    def forward_enc(self, x):
+        x1, x2, x3, x4 = self.bb(x)
+        B, C, H, W = x.shape
+        x1_, x2_, x3_, x4_ = self.bb(F.interpolate(x, size=(H//2, W//2), mode='bilinear', align_corners=True))
+        x1 = torch.cat([x1, F.interpolate(x1_, size=x1.shape[2:], mode='bilinear', align_corners=True)], dim=1)
+        x2 = torch.cat([x2, F.interpolate(x2_, size=x2.shape[2:], mode='bilinear', align_corners=True)], dim=1)
+        x3 = torch.cat([x3, F.interpolate(x3_, size=x3.shape[2:], mode='bilinear', align_corners=True)], dim=1)
+        x4 = torch.cat([x4, F.interpolate(x4_, size=x4.shape[2:], mode='bilinear', align_corners=True)], dim=1)
+        x4 = torch.cat(
+            (
+                *[
+                    F.interpolate(x1, size=x4.shape[2:], mode='bilinear', align_corners=True),
+                    F.interpolate(x2, size=x4.shape[2:], mode='bilinear', align_corners=True),
+                    F.interpolate(x3, size=x4.shape[2:], mode='bilinear', align_corners=True),
+                ][-len(CXT):],
+                x4
+            ),
+            dim=1
+        )
+        return (x1, x2, x3, x4)
+
+    def forward_ori(self, x):
+        (x1, x2, x3, x4) = self.forward_enc(x)
+        x4 = self.squeeze_module(x4)
+        features = [x, x1, x2, x3, x4]
+        scaled_preds = self.decoder(features)
+        return scaled_preds
+
+    def forward(self, pixel_values, intermediate_output=None):
+        scaled_preds = self.forward_ori(pixel_values)
+        return scaled_preds
+
+
+class Decoder(nn.Module):
+    def __init__(self, channels, device, dtype, operations):
+        super(Decoder, self).__init__()
+        # factory kwargs
+        fk = {"device":device, "dtype":dtype, "operations":operations}
+        DecoderBlock = partial(BasicDecBlk, **fk)
+        LateralBlock = partial(BasicLatBlk, **fk)
+        DBlock = partial(SimpleConvs, **fk)
+
+        self.split = True
+        N_dec_ipt = 64
+        ic = 64
+        ipt_cha_opt = 1
+        self.ipt_blk5 = DBlock(2**10*3 if self.split else 3, [N_dec_ipt, channels[0]//8][ipt_cha_opt], inter_channels=ic)
+        self.ipt_blk4 = DBlock(2**8*3 if self.split else 3, [N_dec_ipt, channels[0]//8][ipt_cha_opt], inter_channels=ic)
+        self.ipt_blk3 = DBlock(2**6*3 if self.split else 3, [N_dec_ipt, channels[1]//8][ipt_cha_opt], inter_channels=ic)
+        self.ipt_blk2 = DBlock(2**4*3 if self.split else 3, [N_dec_ipt, channels[2]//8][ipt_cha_opt], inter_channels=ic)
+        self.ipt_blk1 = DBlock(2**0*3 if self.split else 3, [N_dec_ipt, channels[3]//8][ipt_cha_opt], inter_channels=ic)
+
+        self.decoder_block4 = DecoderBlock(channels[0]+([N_dec_ipt, channels[0]//8][ipt_cha_opt]), channels[1])
+        self.decoder_block3 = DecoderBlock(channels[1]+([N_dec_ipt, channels[0]//8][ipt_cha_opt]), channels[2])
+        self.decoder_block2 = DecoderBlock(channels[2]+([N_dec_ipt, channels[1]//8][ipt_cha_opt]), channels[3])
+        self.decoder_block1 = DecoderBlock(channels[3]+([N_dec_ipt, channels[2]//8][ipt_cha_opt]), channels[3]//2)
+
+        fk = {"device":device, "dtype":dtype}
+
+        self.conv_out1 = nn.Sequential(operations.Conv2d(channels[3]//2+([N_dec_ipt, channels[3]//8][ipt_cha_opt]), 1, 1, 1, 0, **fk))
+
+        self.lateral_block4 = LateralBlock(channels[1], channels[1])
+        self.lateral_block3 = LateralBlock(channels[2], channels[2])
+        self.lateral_block2 = LateralBlock(channels[3], channels[3])
+
+        self.conv_ms_spvn_4 = operations.Conv2d(channels[1], 1, 1, 1, 0, **fk)
+        self.conv_ms_spvn_3 = operations.Conv2d(channels[2], 1, 1, 1, 0, **fk)
+        self.conv_ms_spvn_2 = operations.Conv2d(channels[3], 1, 1, 1, 0, **fk)
+
+        _N = 16
+
+        self.gdt_convs_4 = nn.Sequential(operations.Conv2d(channels[0] // 2, _N, 3, 1, 1, **fk), operations.BatchNorm2d(_N, **fk), nn.ReLU(inplace=True))
+        self.gdt_convs_3 = nn.Sequential(operations.Conv2d(channels[1] // 2, _N, 3, 1, 1, **fk), operations.BatchNorm2d(_N, **fk), nn.ReLU(inplace=True))
+        self.gdt_convs_2 = nn.Sequential(operations.Conv2d(channels[2] // 2, _N, 3, 1, 1, **fk), operations.BatchNorm2d(_N, **fk), nn.ReLU(inplace=True))
+
+        [setattr(self, f"gdt_convs_pred_{i}", nn.Sequential(operations.Conv2d(_N, 1, 1, 1, 0, **fk))) for i in range(2, 5)]
+        [setattr(self, f"gdt_convs_attn_{i}", nn.Sequential(operations.Conv2d(_N, 1, 1, 1, 0, **fk))) for i in range(2, 5)]
+
+    def get_patches_batch(self, x, p):
+        _size_h, _size_w = p.shape[2:]
+        patches_batch = []
+        for idx in range(x.shape[0]):
+            columns_x = torch.split(x[idx], split_size_or_sections=_size_w, dim=-1)
+            patches_x = []
+            for column_x in columns_x:
+                patches_x += [p.unsqueeze(0) for p in torch.split(column_x, split_size_or_sections=_size_h, dim=-2)]
+            patch_sample = torch.cat(patches_x, dim=1)
+            patches_batch.append(patch_sample)
+        return torch.cat(patches_batch, dim=0)
+
+    def forward(self, features):
+        x, x1, x2, x3, x4 = features
+
+        patches_batch = self.get_patches_batch(x, x4) if self.split else x
+        x4 = torch.cat((x4, self.ipt_blk5(F.interpolate(patches_batch, size=x4.shape[2:], mode='bilinear', align_corners=True))), 1)
+        p4 = self.decoder_block4(x4)
+        p4_gdt = self.gdt_convs_4(p4)
+        gdt_attn_4 = self.gdt_convs_attn_4(p4_gdt).sigmoid()
+        p4 = p4 * gdt_attn_4
+        _p4 = F.interpolate(p4, size=x3.shape[2:], mode='bilinear', align_corners=True)
+        _p3 = _p4 + self.lateral_block4(x3)
+
+        patches_batch = self.get_patches_batch(x, _p3) if self.split else x
+        _p3 = torch.cat((_p3, self.ipt_blk4(F.interpolate(patches_batch, size=x3.shape[2:], mode='bilinear', align_corners=True))), 1)
+        p3 = self.decoder_block3(_p3)
+
+        p3_gdt = self.gdt_convs_3(p3)
+        gdt_attn_3 = self.gdt_convs_attn_3(p3_gdt).sigmoid()
+        p3 = p3 * gdt_attn_3
+        _p3 = F.interpolate(p3, size=x2.shape[2:], mode='bilinear', align_corners=True)
+        _p2 = _p3 + self.lateral_block3(x2)
+
+        patches_batch = self.get_patches_batch(x, _p2) if self.split else x
+        _p2 = torch.cat((_p2, self.ipt_blk3(F.interpolate(patches_batch, size=x2.shape[2:], mode='bilinear', align_corners=True))), 1)
+        p2 = self.decoder_block2(_p2)
+
+        p2_gdt = self.gdt_convs_2(p2)
+        gdt_attn_2 = self.gdt_convs_attn_2(p2_gdt).sigmoid()
+        p2 = p2 * gdt_attn_2
+
+        _p2 = F.interpolate(p2, size=x1.shape[2:], mode='bilinear', align_corners=True)
+        _p1 = _p2 + self.lateral_block2(x1)
+
+        patches_batch = self.get_patches_batch(x, _p1) if self.split else x
+        _p1 = torch.cat((_p1, self.ipt_blk2(F.interpolate(patches_batch, size=x1.shape[2:], mode='bilinear', align_corners=True))), 1)
+        _p1 = self.decoder_block1(_p1)
+        _p1 = F.interpolate(_p1, size=x.shape[2:], mode='bilinear', align_corners=True)
+
+        patches_batch = self.get_patches_batch(x, _p1) if self.split else x
+        _p1 = torch.cat((_p1, self.ipt_blk1(F.interpolate(patches_batch, size=x.shape[2:], mode='bilinear', align_corners=True))), 1)
+        p1_out = self.conv_out1(_p1)
+        return p1_out
+
+
+class SimpleConvs(nn.Module):
+    def __init__(
+        self, in_channels: int, out_channels: int, inter_channels=64, device=None, dtype=None, operations=None
+    ) -> None:
+        super().__init__()
+        self.conv1 = operations.Conv2d(in_channels, inter_channels, 3, 1, 1, device=device, dtype=dtype)
+        self.conv_out = operations.Conv2d(inter_channels, out_channels, 3, 1, 1, device=device, dtype=dtype)
+
+    def forward(self, x):
+        return self.conv_out(self.conv1(x))
diff --git a/comfy/bg_removal_model.py b/comfy/bg_removal_model.py
new file mode 100644
index 000000000..cb7c2ee53
--- /dev/null
+++ b/comfy/bg_removal_model.py
@@ -0,0 +1,78 @@
+from .utils import load_torch_file
+import os
+import json
+import torch
+import logging
+
+import comfy.ops
+import comfy.model_patcher
+import comfy.model_management
+import comfy.clip_model
+import comfy.background_removal.birefnet
+
+BG_REMOVAL_MODELS = {
+    "birefnet": comfy.background_removal.birefnet.BiRefNet
+}
+
+class BackgroundRemovalModel():
+    def __init__(self, json_config):
+        with open(json_config) as f:
+            config = json.load(f)
+
+        self.image_size = config.get("image_size", 1024)
+        self.image_mean = config.get("image_mean", [0.0, 0.0, 0.0])
+        self.image_std = config.get("image_std", [1.0, 1.0, 1.0])
+        self.model_type = config.get("model_type", "birefnet")
+        self.config = config.copy()
+        model_class = BG_REMOVAL_MODELS.get(self.model_type)
+
+        self.load_device = comfy.model_management.text_encoder_device()
+        offload_device = comfy.model_management.text_encoder_offload_device()
+        self.dtype = comfy.model_management.text_encoder_dtype(self.load_device)
+        self.model = model_class(config, self.dtype, offload_device, comfy.ops.manual_cast)
+        self.model.eval()
+
+        self.patcher = comfy.model_patcher.CoreModelPatcher(self.model, load_device=self.load_device, offload_device=offload_device)
+
+    def load_sd(self, sd):
+        return self.model.load_state_dict(sd, strict=False, assign=self.patcher.is_dynamic())
+
+    def get_sd(self):
+        return self.model.state_dict()
+
+    def encode_image(self, image):
+        comfy.model_management.load_model_gpu(self.patcher)
+        H, W = image.shape[1], image.shape[2]
+        pixel_values = comfy.clip_model.clip_preprocess(image.to(self.load_device), size=self.image_size, mean=self.image_mean, std=self.image_std, crop=False)
+        out = self.model(pixel_values=pixel_values)
+        out = torch.nn.functional.interpolate(out, size=(H, W), mode="bicubic", antialias=False)
+
+        mask = out.sigmoid()
+        if mask.ndim == 3:
+            mask = mask.unsqueeze(0)
+        if mask.shape[1] != 1:
+            mask = mask.movedim(-1, 1)
+
+        return mask
+
+
+def load_background_removal_model(sd):
+    if "bb.layers.1.blocks.0.attn.relative_position_index" in sd:
+        json_config = os.path.join(os.path.join(os.path.dirname(os.path.realpath(__file__)), "background_removal"), "birefnet.json")
+    else:
+        return None
+
+    bg_model = BackgroundRemovalModel(json_config)
+    m, u = bg_model.load_sd(sd)
+    if len(m) > 0:
+        logging.warning("missing background removal: {}".format(m))
+    u = set(u)
+    keys = list(sd.keys())
+    for k in keys:
+        if k not in u:
+            sd.pop(k)
+    return bg_model
+
+def load(ckpt_path):
+    sd = load_torch_file(ckpt_path)
+    return load_background_removal_model(sd)
diff --git a/comfy/ops.py b/comfy/ops.py
index 585c185a3..77ad1d527 100644
--- a/comfy/ops.py
+++ b/comfy/ops.py
@@ -562,6 +562,25 @@ class disable_weight_init:
             else:
                 return super().forward(*args, **kwargs)
 
+    class BatchNorm2d(torch.nn.BatchNorm2d, CastWeightBiasOp):
+        def reset_parameters(self):
+            return None
+
+        def forward_comfy_cast_weights(self, input):
+            weight, bias, offload_stream = cast_bias_weight(self, input, offloadable=True)
+            running_mean = self.running_mean.to(device=input.device, dtype=weight.dtype) if self.running_mean is not None else None
+            running_var = self.running_var.to(device=input.device, dtype=weight.dtype) if self.running_var is not None else None
+            x = torch.nn.functional.batch_norm(input, running_mean, running_var, weight, bias, self.training, self.momentum, self.eps)
+            uncast_bias_weight(self, weight, bias, offload_stream)
+            return x
+
+        def forward(self, *args, **kwargs):
+            run_every_op()
+            if self.comfy_cast_weights or len(self.weight_function) > 0 or len(self.bias_function) > 0:
+                return self.forward_comfy_cast_weights(*args, **kwargs)
+            else:
+                return super().forward(*args, **kwargs)
+
     class LayerNorm(torch.nn.LayerNorm, CastWeightBiasOp):
         def reset_parameters(self):
             return None
@@ -749,6 +768,9 @@ class manual_cast(disable_weight_init):
     class Conv3d(disable_weight_init.Conv3d):
         comfy_cast_weights = True
 
+    class BatchNorm2d(disable_weight_init.BatchNorm2d):
+        comfy_cast_weights = True
+
     class GroupNorm(disable_weight_init.GroupNorm):
         comfy_cast_weights = True
 
diff --git a/comfy_api/latest/_io.py b/comfy_api/latest/_io.py
index e50266bc5..5ed968960 100644
--- a/comfy_api/latest/_io.py
+++ b/comfy_api/latest/_io.py
@@ -17,6 +17,7 @@ if TYPE_CHECKING:
     from spandrel import ImageModelDescriptor
     from comfy.clip_vision import ClipVisionModel
     from comfy.clip_vision import Output as ClipVisionOutput_
+    from comfy.bg_removal_model import BackgroundRemovalModel
     from comfy.controlnet import ControlNet
     from comfy.hooks import HookGroup, HookKeyframeGroup
     from comfy.model_patcher import ModelPatcher
@@ -614,6 +615,11 @@ class Model(ComfyTypeIO):
     if TYPE_CHECKING:
         Type = ModelPatcher
 
+@comfytype(io_type="BACKGROUND_REMOVAL")
+class BackgroundRemoval(ComfyTypeIO):
+    if TYPE_CHECKING:
+        Type = BackgroundRemovalModel
+
 @comfytype(io_type="CLIP_VISION")
 class ClipVision(ComfyTypeIO):
     if TYPE_CHECKING:
@@ -2257,6 +2263,7 @@ __all__ = [
     "ModelPatch",
     "ClipVision",
     "ClipVisionOutput",
+    "BackgroundRemoval",
     "AudioEncoder",
     "AudioEncoderOutput",
     "StyleModel",
diff --git a/comfy_extras/nodes_bg_removal.py b/comfy_extras/nodes_bg_removal.py
new file mode 100644
index 000000000..8d046b8d4
--- /dev/null
+++ b/comfy_extras/nodes_bg_removal.py
@@ -0,0 +1,60 @@
+import folder_paths
+from typing_extensions import override
+from comfy_api.latest import ComfyExtension, IO
+from comfy.bg_removal_model import load
+
+
+class LoadBackgroundRemovalModel(IO.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        files = folder_paths.get_filename_list("background_removal")
+        return IO.Schema(
+            node_id="LoadBackgroundRemovalModel",
+            display_name="Load Background Removal Model",
+            category="loaders",
+            inputs=[
+                IO.Combo.Input("bg_removal_name", options=sorted(files), tooltip="The model used to remove backgrounds from images"),
+            ],
+            outputs=[
+                IO.BackgroundRemoval.Output("bg_model")
+            ]
+        )
+    @classmethod
+    def execute(cls, bg_removal_name):
+        path = folder_paths.get_full_path_or_raise("background_removal", bg_removal_name)
+        bg = load(path)
+        if bg is None:
+            raise RuntimeError("ERROR: background model file is invalid and does not contain a valid background removal model.")
+        return IO.NodeOutput(bg)
+
+class RemoveBackground(IO.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return IO.Schema(
+            node_id="RemoveBackground",
+            display_name="Remove Background",
+            category="image/background removal",
+            inputs=[
+                IO.Image.Input("image", tooltip="Input image to remove the background from"),
+                IO.BackgroundRemoval.Input("bg_removal_model", tooltip="Background removal model used to generate the mask")
+            ],
+            outputs=[
+                IO.Mask.Output("mask", tooltip="Generated foreground mask")
+            ]
+        )
+    @classmethod
+    def execute(cls, image, bg_removal_model):
+        mask = bg_removal_model.encode_image(image)
+        return IO.NodeOutput(mask)
+
+class BackgroundRemovalExtension(ComfyExtension):
+    @override
+    async def get_node_list(self) -> list[type[IO.ComfyNode]]:
+        return [
+            LoadBackgroundRemovalModel,
+            RemoveBackground
+        ]
+
+
+async def comfy_entrypoint() -> BackgroundRemovalExtension:
+    return BackgroundRemovalExtension()
diff --git a/comfy_extras/nodes_mask.py b/comfy_extras/nodes_mask.py
index 43a933dac..c9b2a84d9 100644
--- a/comfy_extras/nodes_mask.py
+++ b/comfy_extras/nodes_mask.py
@@ -40,10 +40,21 @@ def composite(destination, source, x, y, mask = None, multiplier = 8, resize_sou
 
     inverse_mask = torch.ones_like(mask) - mask
 
-    source_portion = mask * source[..., :visible_height, :visible_width]
-    destination_portion = inverse_mask  * destination[..., top:bottom, left:right]
+    source_rgb = source[:, :3, :visible_height, :visible_width]
+    dest_slice = destination[..., top:bottom, left:right]
+
+    if destination.shape[1] == 4:
+        if torch.max(dest_slice) == 0:
+            destination[:, :3, top:bottom, left:right] = source_rgb
+            destination[:, 3:4, top:bottom, left:right] = mask
+        else:
+            destination[:, :3, top:bottom, left:right] = (mask * source_rgb) + (inverse_mask * dest_slice[:, :3])
+            destination[:, 3:4, top:bottom, left:right] = torch.max(mask, dest_slice[:, 3:4])
+    else:
+        source_portion = mask * source_rgb
+        destination_portion = inverse_mask * dest_slice
+        destination[..., top:bottom, left:right] = source_portion + destination_portion
 
-    destination[..., top:bottom, left:right] = source_portion + destination_portion
     return destination
 
 class LatentCompositeMasked(IO.ComfyNode):
@@ -84,18 +95,23 @@ class ImageCompositeMasked(IO.ComfyNode):
             display_name="Image Composite Masked",
             category="image",
             inputs=[
-                IO.Image.Input("destination"),
                 IO.Image.Input("source"),
                 IO.Int.Input("x", default=0, min=0, max=nodes.MAX_RESOLUTION, step=1),
                 IO.Int.Input("y", default=0, min=0, max=nodes.MAX_RESOLUTION, step=1),
                 IO.Boolean.Input("resize_source", default=False),
+                IO.Image.Input("destination", optional=True),
                 IO.Mask.Input("mask", optional=True),
             ],
             outputs=[IO.Image.Output()],
         )
 
     @classmethod
-    def execute(cls, destination, source, x, y, resize_source, mask = None) -> IO.NodeOutput:
+    def execute(cls, source, x, y, resize_source, destination = None, mask = None) -> IO.NodeOutput:
+        if destination is None: # transparent rgba
+            B, H, W, C = source.shape
+            destination = torch.zeros((B, H, W, 4), dtype=source.dtype, device=source.device)
+            if C == 3:
+                source = torch.nn.functional.pad(source, (0, 1), value=1.0)
         destination, source = node_helpers.image_alpha_fix(destination, source)
         destination = destination.clone().movedim(-1, 1)
         output = composite(destination, source.movedim(-1, 1), x, y, mask, 1, resize_source).movedim(1, -1)
@@ -381,7 +397,6 @@ class GrowMask(IO.ComfyNode):
 
     expand_mask = execute  # TODO: remove
 
-
 class ThresholdMask(IO.ComfyNode):
     @classmethod
     def define_schema(cls):
diff --git a/folder_paths.py b/folder_paths.py
index 98d3b1880..92e8df3cf 100644
--- a/folder_paths.py
+++ b/folder_paths.py
@@ -52,6 +52,8 @@ folder_names_and_paths["model_patches"] = ([os.path.join(models_dir, "model_patc
 
 folder_names_and_paths["audio_encoders"] = ([os.path.join(models_dir, "audio_encoders")], supported_pt_extensions)
 
+folder_names_and_paths["background_removal"] = ([os.path.join(models_dir, "background_removal")], supported_pt_extensions)
+
 folder_names_and_paths["frame_interpolation"] = ([os.path.join(models_dir, "frame_interpolation")], supported_pt_extensions)
 
 folder_names_and_paths["optical_flow"] = ([os.path.join(models_dir, "optical_flow")], supported_pt_extensions)
diff --git a/models/background_removal/put_background_removal_models_here b/models/background_removal/put_background_removal_models_here
new file mode 100644
index 000000000..e69de29bb
diff --git a/nodes.py b/nodes.py
index ae9e70cb9..5755f0bb8 100644
--- a/nodes.py
+++ b/nodes.py
@@ -2429,6 +2429,7 @@ async def init_builtin_extra_nodes():
         "nodes_number_convert.py",
         "nodes_painter.py",
         "nodes_curve.py",
+        "nodes_bg_removal.py",
         "nodes_rtdetr.py",
         "nodes_frame_interpolation.py",
         "nodes_sam3.py",

From 05cd076bc1d9386ec77414c96d1460008f653f7c Mon Sep 17 00:00:00 2001
From: drozbay <17261091+drozbay@users.noreply.github.com>
Date: Fri, 8 May 2026 08:48:59 -0600
Subject: [PATCH 02/10] fix: Make LTXVAddGuide center-crop guide images to
 match other LTXV nodes (#13794)

---
 comfy_extras/nodes_lt.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/comfy_extras/nodes_lt.py b/comfy_extras/nodes_lt.py
index ab1359fdb..f1f4d5319 100644
--- a/comfy_extras/nodes_lt.py
+++ b/comfy_extras/nodes_lt.py
@@ -236,7 +236,7 @@ class LTXVAddGuide(io.ComfyNode):
     def encode(cls, vae, latent_width, latent_height, images, scale_factors):
         time_scale_factor, width_scale_factor, height_scale_factor = scale_factors
         images = images[:(images.shape[0] - 1) // time_scale_factor * time_scale_factor + 1]
-        pixels = comfy.utils.common_upscale(images.movedim(-1, 1), latent_width * width_scale_factor, latent_height * height_scale_factor, "bilinear", crop="disabled").movedim(1, -1)
+        pixels = comfy.utils.common_upscale(images.movedim(-1, 1), latent_width * width_scale_factor, latent_height * height_scale_factor, "bilinear", crop="center").movedim(1, -1)
         encode_pixels = pixels[:, :, :, :3]
         t = vae.encode(encode_pixels)
         return encode_pixels, t

From 9864f5ac86778221d730c9626952a1ee15c16994 Mon Sep 17 00:00:00 2001
From: drozbay <17261091+drozbay@users.noreply.github.com>
Date: Fri, 8 May 2026 09:02:17 -0600
Subject: [PATCH 03/10] fix: Stop LTXVImgToVideoInplace from mutating input
 latents and dropping noise_mask (#13793)

---
 comfy_extras/nodes_lt.py | 10 +++-------
 1 file changed, 3 insertions(+), 7 deletions(-)

diff --git a/comfy_extras/nodes_lt.py b/comfy_extras/nodes_lt.py
index f1f4d5319..a4c85db77 100644
--- a/comfy_extras/nodes_lt.py
+++ b/comfy_extras/nodes_lt.py
@@ -106,12 +106,12 @@ class LTXVImgToVideoInplace(io.ComfyNode):
         if bypass:
             return (latent,)
 
-        samples = latent["samples"]
+        samples = latent["samples"].clone()
         _, height_scale_factor, width_scale_factor = (
             vae.downscale_index_formula
         )
 
-        batch, _, latent_frames, latent_height, latent_width = samples.shape
+        _, _, _, latent_height, latent_width = samples.shape
         width = latent_width * width_scale_factor
         height = latent_height * height_scale_factor
 
@@ -124,11 +124,7 @@ class LTXVImgToVideoInplace(io.ComfyNode):
 
         samples[:, :, :t.shape[2]] = t
 
-        conditioning_latent_frames_mask = torch.ones(
-            (batch, 1, latent_frames, 1, 1),
-            dtype=torch.float32,
-            device=samples.device,
-        )
+        conditioning_latent_frames_mask = get_noise_mask(latent)
         conditioning_latent_frames_mask[:, :, :t.shape[2]] = 1.0 - strength
 
         return io.NodeOutput({"samples": samples, "noise_mask": conditioning_latent_frames_mask})

From c5ecd231a2aa41124ec6a958416d166d7dcb81fb Mon Sep 17 00:00:00 2001
From: Alexis Rolland <alexisrolland@hotmail.com>
Date: Fri, 8 May 2026 23:06:29 +0800
Subject: [PATCH 04/10] fix: Fix bug when mask not on same device (CORE-181)
 (#13801)

---
 comfy/bg_removal_model.py         | 2 +-
 comfy_extras/nodes_compositing.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/comfy/bg_removal_model.py b/comfy/bg_removal_model.py
index cb7c2ee53..7877afd7f 100644
--- a/comfy/bg_removal_model.py
+++ b/comfy/bg_removal_model.py
@@ -47,7 +47,7 @@ class BackgroundRemovalModel():
         out = self.model(pixel_values=pixel_values)
         out = torch.nn.functional.interpolate(out, size=(H, W), mode="bicubic", antialias=False)
 
-        mask = out.sigmoid()
+        mask = out.sigmoid().to(device=comfy.model_management.intermediate_device(), dtype=comfy.model_management.intermediate_dtype())
         if mask.ndim == 3:
             mask = mask.unsqueeze(0)
         if mask.shape[1] != 1:
diff --git a/comfy_extras/nodes_compositing.py b/comfy_extras/nodes_compositing.py
index 5b4423734..720efc629 100644
--- a/comfy_extras/nodes_compositing.py
+++ b/comfy_extras/nodes_compositing.py
@@ -203,7 +203,7 @@ class JoinImageWithAlpha(io.ComfyNode):
     @classmethod
     def execute(cls, image: torch.Tensor, alpha: torch.Tensor) -> io.NodeOutput:
         batch_size = max(len(image), len(alpha))
-        alpha = 1.0 - resize_mask(alpha, image.shape[1:])
+        alpha = 1.0 - resize_mask(alpha.to(image), image.shape[1:])
         alpha = comfy.utils.repeat_to_batch_size(alpha, batch_size)
         image = comfy.utils.repeat_to_batch_size(image, batch_size)
         return io.NodeOutput(torch.cat((image[..., :3], alpha.unsqueeze(-1)), dim=-1))

From 87878f354f4d49446ed81b5ebfb98b12dda37c7c Mon Sep 17 00:00:00 2001
From: Matt Miller <mattmiller@comfy.org>
Date: Fri, 8 May 2026 12:39:16 -0700
Subject: [PATCH 05/10] Add cloud-runtime FE-facing operations to spec (#13734)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Add cloud-runtime FE-facing operations to openapi.yaml

Add ~67 cloud-runtime FE-facing path operations to the core OpenAPI spec,
each tagged with x-runtime: [cloud] at the operation level. These operations
are served by the cloud runtime; the local runtime returns 404 for all of
these paths.

Domain groups added:
- Jobs / prompts: /api/job/*, /api/jobs/*/cancel, /api/prompt/*, etc.
- History v2: /api/history_v2, /api/history_v2/{prompt_id}
- Cloud logs: /api/logs
- Asset extensions: /api/assets/download, export, import, etc.
- Custom nodes: /api/experiment/nodes (cloud install/uninstall)
- Hub: /api/hub/profiles, /api/hub/workflows, /api/hub/labels, etc.
- Workflows: /api/workflows CRUD, versioning, fork, publish
- Auth/session: /api/auth/session, /api/auth/token, /.well-known/jwks.json
- Billing: /api/billing/balance, plans, subscribe, topup, etc.
- Workspace: /api/workspace/*, /api/workspaces/*
- User/settings/misc: /api/user, /api/secrets, /api/feedback, etc.

Also adds corresponding cloud-only component schemas (CloudJob, CloudWorkflow,
BillingPlan, Workspace, HubProfile, AuthSession, etc.), all tagged with
x-runtime: [cloud].

Spectral lint passes under the existing ruleset with zero new warnings.

* Add job_id field to Asset schema and deprecate prompt_id (#13736)

- Add job_id as a nullable UUID field to the Asset schema
- Mark prompt_id as deprecated with note pointing to job_id
- No x-runtime tag needed as both runtimes populate the field

* Add hash field to Asset schemas and deprecate asset_hash (#13738)

- Add 'hash' as a nullable string field to Asset and AssetUpdated schemas
- Mark 'asset_hash' as deprecated with a note pointing to 'hash'
- AssetCreated inherits 'hash' via allOf from Asset
- Spectral lint clean (no new warnings)

* Fix method drift on cloud-runtime endpoints

Three PUT operations were added that should be PATCH (cloud serves
PATCH for partial updates):

- /api/workflows/{workflow_id}
- /api/workspaces/{id}
- /api/workspace/members/{userId}

Two POST operations were added that should be GET (cloud serves GET
with query params):

- /api/assets/remote-metadata (url moves to query param)
- /api/files/mask-layers (response shape replaced — operation queries
  related mask layer filenames, not file uploads)

* Add missing cloud-runtime operations and schemas

PR review surfaced operations the cloud runtime serves that weren't
covered by the initial spec push, plus one path family missed entirely.

New methods on existing paths:

- /api/auth/session: add POST (create session cookie) and DELETE (logout)
- /api/secrets/{id}: add GET (read metadata) and PATCH (update)
- /api/hub/profiles: add POST (create profile)
- /api/hub/workflows: add POST (publish to hub)
- /api/hub/workflows/{share_id}: add DELETE (unpublish)
- /api/workspaces/{id}: add DELETE (soft-delete workspace)
- /api/workspace/members/{user_id}/api-keys: add DELETE (bulk revoke)
- /api/workflows/{workflow_id}/versions: add POST (create new version)
- /api/userdata/{file}/publish: add GET (read publish info)

New path family:

- /api/tasks (GET list) and /api/tasks/{task_id} (GET detail) for the
  background task framework

New component schemas (all tagged x-runtime: [cloud]):

CreateSessionResponse, DeleteSessionResponse, UpdateSecretRequest,
BulkRevokeAPIKeysResponse, CreateHubProfileRequest, PublishHubWorkflowRequest,
HubWorkflowDetail, AssetInfo, CreateWorkflowVersionRequest,
WorkflowVersionResponse, WorkflowPublishInfo, TaskEntry, TaskResponse,
TasksListResponse. Existing SecretMeta extended with provider and
last_used_at fields the cloud runtime actually returns.

New tag: task. Spectral lint passes with zero errors.

* Add job_id and prompt_id to AssetUpdated schema

Mirrors the Asset schema's deprecation pattern: prompt_id is marked
deprecated with a description pointing to job_id; job_id is the new
preferred field. PUT /api/assets/{id} responses can now carry both fields
consistent with the other Asset-returning endpoints.

* feat: add width and height fields to Asset schema (#13745)

Add nullable integer fields 'width' and 'height' to the Asset schema
in openapi.yaml. These expose original image dimensions in pixels for
clients that need pre-thumbnail size info. Both fields are null for
non-image assets or assets ingested before dimension extraction.

Co-authored-by: Matt Miller <MillerMedia@users.noreply.github.com>

* Remove /api/job/{job_id} and /api/job/{job_id}/outputs

These two paths are not actually served by the cloud runtime — they
return 404 with a redirect message pointing callers to the canonical
`/api/jobs/{job_id}` (plural). Declaring them with `x-runtime: [cloud]`
and a 200 response schema is incorrect.

`/api/job/{job_id}/status` stays — it is a real cloud-served endpoint.

Also drops the now-orphaned `CloudJob` and `CloudJobOutputs` component
schemas. `CloudJobStatus` is retained.
---
 openapi.yaml | 4716 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 4714 insertions(+), 2 deletions(-)

diff --git a/openapi.yaml b/openapi.yaml
index 29b5f544b..4216c1a6c 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -62,6 +62,19 @@ tags:
   - name: assets
     description: Asset management (feature-gated behind enable-assets)
 
+  - name: auth
+    description: Authentication and session management (cloud-only)
+  - name: billing
+    description: Billing, subscriptions, and payment management (cloud-only)
+  - name: workspace
+    description: Workspace and team management (cloud-only)
+  - name: hub
+    description: "ComfyUI Hub: profiles, shared workflows, and labels (cloud-only)"
+  - name: workflows
+    description: Cloud workflow management and versioning (cloud-only)
+  - name: task
+    description: Background task management (cloud-only)
+
 paths:
   # ---------------------------------------------------------------------------
   # WebSocket
@@ -2056,6 +2069,3449 @@ paths:
                     type: integer
                     description: Number of assets marked as missing
 
+
+  # ===========================================================================
+  # Cloud-runtime FE-facing operations
+  #
+  # These operations are served by the cloud runtime. The local runtime returns
+  # 404 for all of these paths. Each operation is tagged x-runtime: [cloud].
+  # ===========================================================================
+
+  # ---------------------------------------------------------------------------
+  # Jobs / prompts (cloud)
+  # ---------------------------------------------------------------------------
+  /api/jobs/{job_id}/cancel:
+    post:
+      operationId: cancelJob
+      tags: [queue]
+      summary: Cancel a running or pending job
+      description: "[cloud-only] Requests cancellation of a job. If the job is currently executing, execution is interrupted. If it is pending in the queue, it is removed."
+      x-runtime: [cloud]
+      parameters:
+        - name: job_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The job ID to cancel.
+      responses:
+        "200":
+          description: Cancellation accepted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudJobStatus"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/job/{job_id}/status:
+    get:
+      operationId: getCloudJobStatus
+      tags: [queue]
+      summary: Get status of a cloud job
+      description: "[cloud-only] Returns the current execution status of a cloud job."
+      x-runtime: [cloud]
+      parameters:
+        - name: job_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The job ID to check status for.
+      responses:
+        "200":
+          description: Job status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudJobStatus"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/prompt/{prompt_id}:
+    get:
+      operationId: getCloudPrompt
+      tags: [prompt]
+      summary: Get a cloud prompt by ID
+      description: "[cloud-only] Returns the full prompt record for a cloud-executed prompt, including the submitted workflow graph and execution metadata."
+      x-runtime: [cloud]
+      parameters:
+        - name: prompt_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The prompt ID to fetch.
+      responses:
+        "200":
+          description: Cloud prompt detail
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudPrompt"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/history_v2:
+    get:
+      operationId: getHistoryV2
+      tags: [history]
+      summary: Get paginated execution history (v2)
+      description: "[cloud-only] Returns a paginated list of execution history entries in the v2 format, with richer metadata than the legacy history endpoint."
+      x-runtime: [cloud]
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 20
+          description: Maximum number of results
+        - name: offset
+          in: query
+          schema:
+            type: integer
+            default: 0
+          description: Pagination offset
+        - name: status
+          in: query
+          schema:
+            type: string
+          description: Filter by execution status
+      responses:
+        "200":
+          description: History list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HistoryV2Response"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/history_v2/{prompt_id}:
+    get:
+      operationId: getHistoryV2ByPromptId
+      tags: [history]
+      summary: Get v2 history for a specific prompt
+      description: "[cloud-only] Returns the v2 history entry for a specific prompt execution."
+      x-runtime: [cloud]
+      parameters:
+        - name: prompt_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The prompt ID to fetch history for.
+      responses:
+        "200":
+          description: History entry
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HistoryV2Entry"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/logs:
+    get:
+      operationId: getCloudLogs
+      tags: [system]
+      summary: Get cloud execution logs
+      description: "[cloud-only] Returns execution logs for the authenticated user's cloud jobs."
+      x-runtime: [cloud]
+      parameters:
+        - name: job_id
+          in: query
+          schema:
+            type: string
+          description: Filter logs by job ID
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 100
+          description: Maximum number of log entries
+        - name: offset
+          in: query
+          schema:
+            type: integer
+            default: 0
+          description: Pagination offset
+      responses:
+        "200":
+          description: Log entries
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudLogsResponse"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  # ---------------------------------------------------------------------------
+  # Assets extensions (cloud)
+  # ---------------------------------------------------------------------------
+  /api/assets/download:
+    post:
+      operationId: downloadAssets
+      tags: [assets]
+      summary: Download assets to cloud runtime
+      description: "[cloud-only] Initiates a download of one or more assets to the cloud runtime environment. Returns a task ID for tracking download progress via WebSocket."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - assets
+              properties:
+                assets:
+                  type: array
+                  items:
+                    $ref: "#/components/schemas/AssetDownloadRequest"
+                  description: Assets to download
+      responses:
+        "200":
+          description: Download initiated
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  task_id:
+                    type: string
+                    description: Task ID for tracking progress via WebSocket
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/assets/export:
+    post:
+      operationId: exportAssets
+      tags: [assets]
+      summary: Export assets as a downloadable archive
+      description: "[cloud-only] Initiates a bulk export of assets. Returns a task ID for tracking progress via WebSocket. When complete, the export can be downloaded via the exports endpoint."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - asset_ids
+              properties:
+                asset_ids:
+                  type: array
+                  items:
+                    type: string
+                    format: uuid
+                  description: IDs of assets to export
+                export_name:
+                  type: string
+                  description: Name for the export archive
+      responses:
+        "200":
+          description: Export initiated
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  task_id:
+                    type: string
+                  export_name:
+                    type: string
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/assets/exports/{exportName}:
+    get:
+      operationId: getAssetExport
+      tags: [assets]
+      summary: Download a completed asset export
+      description: "[cloud-only] Returns the archive file for a completed asset export."
+      x-runtime: [cloud]
+      parameters:
+        - name: exportName
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Name of the export to download
+      responses:
+        "200":
+          description: Export archive file
+          content:
+            application/zip:
+              schema:
+                type: string
+                format: binary
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/assets/from-workflow:
+    post:
+      operationId: createAssetsFromWorkflow
+      tags: [assets]
+      summary: Create asset records from a workflow execution
+      description: "[cloud-only] Registers output files from a workflow execution as assets in the asset database."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - prompt_id
+              properties:
+                prompt_id:
+                  type: string
+                  format: uuid
+                  description: Prompt ID whose outputs should be registered as assets
+                tags:
+                  type: array
+                  items:
+                    type: string
+                  description: Tags to apply to the created assets
+      responses:
+        "201":
+          description: Assets created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  assets:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/Asset"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/assets/import:
+    post:
+      operationId: importAssets
+      tags: [assets]
+      summary: Import assets from external URLs
+      description: "[cloud-only] Imports one or more assets from external URLs into the cloud asset store."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - imports
+              properties:
+                imports:
+                  type: array
+                  items:
+                    $ref: "#/components/schemas/AssetImportRequest"
+                  description: Assets to import
+      responses:
+        "200":
+          description: Import initiated
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  assets:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/Asset"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/assets/remote-metadata:
+    get:
+      operationId: getAssetRemoteMetadata
+      tags: [assets]
+      summary: Fetch metadata for a remote asset URL
+      description: "[cloud-only] Fetches and returns metadata (content type, size, filename) for a remote URL without downloading the full content."
+      x-runtime: [cloud]
+      parameters:
+        - name: url
+          in: query
+          required: true
+          schema:
+            type: string
+            format: uri
+          description: URL to inspect
+      responses:
+        "200":
+          description: Remote metadata
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RemoteAssetMetadata"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  # ---------------------------------------------------------------------------
+  # Custom nodes / hub (cloud)
+  # ---------------------------------------------------------------------------
+  /api/experiment/nodes:
+    get:
+      operationId: listCloudNodes
+      tags: [node]
+      summary: List installed custom nodes
+      description: "[cloud-only] Returns the list of custom node packages installed in the cloud runtime."
+      x-runtime: [cloud]
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+          description: Maximum number of results
+        - name: offset
+          in: query
+          schema:
+            type: integer
+          description: Pagination offset
+      responses:
+        "200":
+          description: Custom node list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudNodeList"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    post:
+      operationId: installCloudNode
+      tags: [node]
+      summary: Install a custom node package
+      description: "[cloud-only] Installs a custom node package in the cloud runtime by ID or repository URL."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - id
+              properties:
+                id:
+                  type: string
+                  description: Node package ID or repository URL
+                version:
+                  type: string
+                  description: Specific version to install
+      responses:
+        "200":
+          description: Node installed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudNode"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/experiment/nodes/{id}:
+    get:
+      operationId: getCloudNode
+      tags: [node]
+      summary: Get details of an installed custom node
+      description: "[cloud-only] Returns details about a specific installed custom node package."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Custom node package ID
+      responses:
+        "200":
+          description: Node detail
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudNode"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    delete:
+      operationId: uninstallCloudNode
+      tags: [node]
+      summary: Uninstall a custom node package
+      description: "[cloud-only] Removes a custom node package from the cloud runtime."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Custom node package ID
+      responses:
+        "204":
+          description: Node uninstalled
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/hub/assets/upload-url:
+    post:
+      operationId: getHubAssetUploadUrl
+      tags: [hub]
+      summary: Get a pre-signed upload URL for a hub asset
+      description: "[cloud-only] Returns a pre-signed URL that can be used to upload an asset file directly to storage."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - filename
+                - content_type
+              properties:
+                filename:
+                  type: string
+                  description: Name of the file to upload
+                content_type:
+                  type: string
+                  description: MIME type of the file
+                size:
+                  type: integer
+                  format: int64
+                  description: File size in bytes
+      responses:
+        "200":
+          description: Upload URL
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  upload_url:
+                    type: string
+                    format: uri
+                    description: Pre-signed upload URL
+                  asset_url:
+                    type: string
+                    format: uri
+                    description: Public URL after upload completes
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/hub/labels:
+    get:
+      operationId: listHubLabels
+      tags: [hub]
+      summary: List available hub labels
+      description: "[cloud-only] Returns the list of labels/categories available for tagging hub content."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Label list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/HubLabel"
+
+  /api/hub/profiles:
+    get:
+      operationId: listHubProfiles
+      tags: [hub]
+      summary: List hub user profiles
+      description: "[cloud-only] Returns a paginated list of public hub user profiles."
+      x-runtime: [cloud]
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+          description: Maximum number of results
+        - name: offset
+          in: query
+          schema:
+            type: integer
+          description: Pagination offset
+        - name: search
+          in: query
+          schema:
+            type: string
+          description: Search by username or display name
+      responses:
+        "200":
+          description: Profile list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  profiles:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/HubProfile"
+                  total:
+                    type: integer
+                  has_more:
+                    type: boolean
+    post:
+      operationId: createHubProfile
+      tags: [hub]
+      summary: Create a Hub profile
+      description: "[cloud-only] Creates a hub profile for the specified workspace. Username is immutable after creation."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateHubProfileRequest"
+      responses:
+        "201":
+          description: Hub profile created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HubProfile"
+        "400":
+          description: Bad request (e.g. invalid username)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "409":
+          description: Username already taken or profile already exists
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/hub/profiles/{username}:
+    get:
+      operationId: getHubProfile
+      tags: [hub]
+      summary: Get a hub profile by username
+      description: "[cloud-only] Returns the public hub profile for the given username."
+      x-runtime: [cloud]
+      parameters:
+        - name: username
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Hub username
+      responses:
+        "200":
+          description: Profile
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HubProfile"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/hub/profiles/check:
+    get:
+      operationId: checkHubProfileUsername
+      tags: [hub]
+      summary: Check if a hub username is available
+      description: "[cloud-only] Returns whether the given username is available for registration."
+      x-runtime: [cloud]
+      parameters:
+        - name: username
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Username to check
+      responses:
+        "200":
+          description: Availability result
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  available:
+                    type: boolean
+                  username:
+                    type: string
+
+  /api/hub/profiles/me:
+    get:
+      operationId: getMyHubProfile
+      tags: [hub]
+      summary: Get the authenticated user's hub profile
+      description: "[cloud-only] Returns the hub profile of the currently authenticated user."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Profile
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HubProfile"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    put:
+      operationId: updateMyHubProfile
+      tags: [hub]
+      summary: Update the authenticated user's hub profile
+      description: "[cloud-only] Updates the hub profile of the currently authenticated user."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                username:
+                  type: string
+                display_name:
+                  type: string
+                bio:
+                  type: string
+                avatar_url:
+                  type: string
+                  format: uri
+                links:
+                  type: array
+                  items:
+                    type: string
+                    format: uri
+      responses:
+        "200":
+          description: Updated profile
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HubProfile"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "409":
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/hub/workflows:
+    get:
+      operationId: listHubWorkflows
+      tags: [hub]
+      summary: List published hub workflows
+      description: "[cloud-only] Returns a paginated list of publicly shared workflows on the hub."
+      x-runtime: [cloud]
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+          description: Maximum number of results
+        - name: offset
+          in: query
+          schema:
+            type: integer
+          description: Pagination offset
+        - name: sort
+          in: query
+          schema:
+            type: string
+          description: Sort field (e.g. created_at, likes)
+        - name: order
+          in: query
+          schema:
+            type: string
+            enum: [asc, desc]
+          description: Sort direction
+        - name: search
+          in: query
+          schema:
+            type: string
+          description: Search by title or description
+        - name: labels
+          in: query
+          schema:
+            type: string
+          description: Filter by label IDs (comma-separated)
+      responses:
+        "200":
+          description: Hub workflow list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HubWorkflowList"
+    post:
+      operationId: publishHubWorkflow
+      tags: [hub]
+      summary: Publish a workflow to the hub
+      description: "[cloud-only] Publishes a workflow to the hub with metadata, thumbnail, and sample images."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PublishHubWorkflowRequest"
+      responses:
+        "200":
+          description: Workflow published to hub
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HubWorkflowDetail"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Workflow or profile not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/hub/workflows/{share_id}:
+    get:
+      operationId: getHubWorkflow
+      tags: [hub]
+      summary: Get a published hub workflow by share ID
+      description: "[cloud-only] Returns the full details of a published workflow on the hub."
+      x-runtime: [cloud]
+      parameters:
+        - name: share_id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Workflow share ID
+      responses:
+        "200":
+          description: Hub workflow
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HubWorkflow"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    delete:
+      operationId: deleteHubWorkflow
+      tags: [hub]
+      summary: Unpublish a workflow from the hub
+      description: "[cloud-only] Removes a workflow from the hub listing."
+      x-runtime: [cloud]
+      parameters:
+        - name: share_id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Workflow share ID
+      responses:
+        "204":
+          description: Successfully unpublished
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Workflow not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/hub/workflows/index:
+    get:
+      operationId: getHubWorkflowIndex
+      tags: [hub]
+      summary: Get the hub workflow index
+      description: "[cloud-only] Returns the lightweight index of all hub workflows for client-side search and navigation."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Workflow index
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/HubWorkflowIndexEntry"
+
+  # ---------------------------------------------------------------------------
+  # Workflows (cloud)
+  # ---------------------------------------------------------------------------
+  /api/workflows:
+    get:
+      operationId: listCloudWorkflows
+      tags: [workflows]
+      summary: List cloud workflows
+      description: "[cloud-only] Returns a paginated list of the authenticated user's cloud workflows."
+      x-runtime: [cloud]
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+          description: Maximum number of results
+        - name: offset
+          in: query
+          schema:
+            type: integer
+          description: Pagination offset
+        - name: sort
+          in: query
+          schema:
+            type: string
+          description: Sort field
+        - name: order
+          in: query
+          schema:
+            type: string
+            enum: [asc, desc]
+          description: Sort direction
+        - name: search
+          in: query
+          schema:
+            type: string
+          description: Search by workflow name
+      responses:
+        "200":
+          description: Workflow list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudWorkflowList"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    post:
+      operationId: createCloudWorkflow
+      tags: [workflows]
+      summary: Create a new cloud workflow
+      description: "[cloud-only] Creates a new cloud workflow with the provided name and optional initial content."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - name
+              properties:
+                name:
+                  type: string
+                  description: Workflow name
+                description:
+                  type: string
+                  description: Workflow description
+                content:
+                  type: object
+                  additionalProperties: true
+                  description: Initial workflow graph JSON
+      responses:
+        "201":
+          description: Workflow created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudWorkflow"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workflows/{workflow_id}:
+    get:
+      operationId: getCloudWorkflow
+      tags: [workflows]
+      summary: Get a cloud workflow by ID
+      description: "[cloud-only] Returns the metadata for a cloud workflow."
+      x-runtime: [cloud]
+      parameters:
+        - name: workflow_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The workflow ID.
+      responses:
+        "200":
+          description: Workflow detail
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudWorkflow"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    patch:
+      operationId: updateCloudWorkflow
+      tags: [workflows]
+      summary: Update a cloud workflow
+      description: "[cloud-only] Updates the metadata (name, description) of an existing cloud workflow."
+      x-runtime: [cloud]
+      parameters:
+        - name: workflow_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The workflow ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                description:
+                  type: string
+      responses:
+        "200":
+          description: Workflow updated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudWorkflow"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    delete:
+      operationId: deleteCloudWorkflow
+      tags: [workflows]
+      summary: Delete a cloud workflow
+      description: "[cloud-only] Deletes a cloud workflow and all its versions."
+      x-runtime: [cloud]
+      parameters:
+        - name: workflow_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The workflow ID.
+      responses:
+        "204":
+          description: Workflow deleted
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workflows/{workflow_id}/content:
+    get:
+      operationId: getCloudWorkflowContent
+      tags: [workflows]
+      summary: Get the content of a cloud workflow
+      description: "[cloud-only] Returns the full workflow graph JSON for the latest version of a cloud workflow."
+      x-runtime: [cloud]
+      parameters:
+        - name: workflow_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The workflow ID.
+        - name: version_id
+          in: query
+          schema:
+            type: string
+          description: Specific version ID to fetch
+      responses:
+        "200":
+          description: Workflow content
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+                description: The full workflow graph JSON
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    put:
+      operationId: updateCloudWorkflowContent
+      tags: [workflows]
+      summary: Update the content of a cloud workflow
+      description: "[cloud-only] Saves new workflow graph JSON as a new version of the cloud workflow."
+      x-runtime: [cloud]
+      parameters:
+        - name: workflow_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The workflow ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
+              description: The workflow graph JSON to save
+      responses:
+        "200":
+          description: Content updated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudWorkflowVersion"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workflows/{workflow_id}/fork:
+    post:
+      operationId: forkCloudWorkflow
+      tags: [workflows]
+      summary: Fork a cloud workflow
+      description: "[cloud-only] Creates a copy of a cloud workflow under the authenticated user's account."
+      x-runtime: [cloud]
+      parameters:
+        - name: workflow_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The workflow ID to fork.
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                  description: Name for the forked workflow (defaults to original name)
+      responses:
+        "201":
+          description: Forked workflow
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudWorkflow"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workflows/{workflow_id}/versions:
+    get:
+      operationId: listCloudWorkflowVersions
+      tags: [workflows]
+      summary: List versions of a cloud workflow
+      description: "[cloud-only] Returns the version history of a cloud workflow."
+      x-runtime: [cloud]
+      parameters:
+        - name: workflow_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The workflow ID.
+        - name: limit
+          in: query
+          schema:
+            type: integer
+          description: Maximum number of results
+        - name: offset
+          in: query
+          schema:
+            type: integer
+          description: Pagination offset
+      responses:
+        "200":
+          description: Version list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  versions:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/CloudWorkflowVersion"
+                  total:
+                    type: integer
+                  has_more:
+                    type: boolean
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    post:
+      operationId: createCloudWorkflowVersion
+      tags: [workflows]
+      summary: Create a new cloud workflow version
+      description: "[cloud-only] Creates a new workflow version with updated workflow JSON. Uses optimistic concurrency via base_version."
+      x-runtime: [cloud]
+      parameters:
+        - name: workflow_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The workflow ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateWorkflowVersionRequest"
+      responses:
+        "201":
+          description: Version created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkflowVersionResponse"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden — not the workflow owner
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "409":
+          description: Version conflict — base_version does not match latest
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workflows/published/{share_id}:
+    get:
+      operationId: getPublishedWorkflow
+      tags: [workflows]
+      summary: Get a published workflow by share ID
+      description: "[cloud-only] Returns a publicly published cloud workflow by its share identifier."
+      x-runtime: [cloud]
+      parameters:
+        - name: share_id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The workflow share ID.
+      responses:
+        "200":
+          description: Published workflow
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudWorkflow"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  # ---------------------------------------------------------------------------
+  # Auth / session (cloud)
+  # ---------------------------------------------------------------------------
+  /api/auth/session:
+    get:
+      operationId: getAuthSession
+      tags: [auth]
+      summary: Get the current authentication session
+      description: "[cloud-only] Returns the current session state for the authenticated user, including user identity and active workspace."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Session info
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AuthSession"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    post:
+      operationId: createAuthSession
+      tags: [auth]
+      summary: Create a session cookie
+      description: "[cloud-only] Creates a session cookie from the bearer token in the Authorization header. Returns a Set-Cookie header with a secure HttpOnly session cookie. Cookie authentication is not allowed for this endpoint."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Session created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CreateSessionResponse"
+        "400":
+          description: Bad request — invalid or expired ID token
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    delete:
+      operationId: deleteAuthSession
+      tags: [auth]
+      summary: Delete session cookie (logout)
+      description: "[cloud-only] Clears the session cookie and optionally revokes the session on the server."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Session deleted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeleteSessionResponse"
+
+  /api/auth/token:
+    post:
+      operationId: createAuthToken
+      tags: [auth]
+      summary: Exchange credentials for an access token
+      description: "[cloud-only] Exchanges authentication credentials (e.g. an authorization code) for an access token."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - grant_type
+              properties:
+                grant_type:
+                  type: string
+                  enum: [authorization_code, refresh_token]
+                  description: OAuth2 grant type
+                code:
+                  type: string
+                  description: Authorization code (for authorization_code grant)
+                refresh_token:
+                  type: string
+                  description: Refresh token (for refresh_token grant)
+                redirect_uri:
+                  type: string
+                  format: uri
+                  description: Redirect URI used in the authorization request
+      responses:
+        "200":
+          description: Token response
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AuthTokenResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /.well-known/jwks.json:
+    get:
+      operationId: getJwks
+      tags: [auth]
+      summary: Get JSON Web Key Set
+      description: "[cloud-only] Returns the JSON Web Key Set (JWKS) used to verify JWTs issued by the cloud authentication service."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: JWKS
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JwksResponse"
+
+  # ---------------------------------------------------------------------------
+  # Billing (cloud)
+  # ---------------------------------------------------------------------------
+  /api/billing/balance:
+    get:
+      operationId: getBillingBalance
+      tags: [billing]
+      summary: Get current credit balance
+      description: "[cloud-only] Returns the authenticated user's current credit balance and usage summary."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Balance info
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingBalance"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/events:
+    get:
+      operationId: listBillingEvents
+      tags: [billing]
+      summary: List billing events
+      description: "[cloud-only] Returns a paginated list of billing events (charges, credits, refunds) for the authenticated user."
+      x-runtime: [cloud]
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+          description: Maximum number of results
+        - name: offset
+          in: query
+          schema:
+            type: integer
+          description: Pagination offset
+        - name: type
+          in: query
+          schema:
+            type: string
+          description: Filter by event type
+      responses:
+        "200":
+          description: Billing events
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingEventList"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/ops/{id}:
+    get:
+      operationId: getBillingOp
+      tags: [billing]
+      summary: Get a billing operation by ID
+      description: "[cloud-only] Returns details of a specific billing operation."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The billing operation ID.
+      responses:
+        "200":
+          description: Billing operation
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingOp"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/payment-portal:
+    post:
+      operationId: createPaymentPortalSession
+      tags: [billing]
+      summary: Create a payment portal session
+      description: "[cloud-only] Creates a Stripe customer portal session for managing payment methods and invoices. Returns a URL to redirect the user to."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Portal session
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  url:
+                    type: string
+                    format: uri
+                    description: Stripe portal URL
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/plans:
+    get:
+      operationId: listBillingPlans
+      tags: [billing]
+      summary: List available billing plans
+      description: "[cloud-only] Returns the list of available subscription plans and their pricing."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Plan list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/BillingPlan"
+
+  /api/billing/preview-subscribe:
+    post:
+      operationId: previewSubscription
+      tags: [billing]
+      summary: Preview a subscription change
+      description: "[cloud-only] Returns a preview of what a subscription change would cost, including prorations."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - plan_id
+              properties:
+                plan_id:
+                  type: string
+                  description: ID of the plan to preview
+      responses:
+        "200":
+          description: Subscription preview
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SubscriptionPreview"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/status:
+    get:
+      operationId: getBillingStatus
+      tags: [billing]
+      summary: Get billing status
+      description: "[cloud-only] Returns the authenticated user's current billing and subscription status."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Billing status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingStatus"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/subscribe:
+    post:
+      operationId: createSubscription
+      tags: [billing]
+      summary: Subscribe to a billing plan
+      description: "[cloud-only] Creates a new subscription to the specified billing plan."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - plan_id
+              properties:
+                plan_id:
+                  type: string
+                  description: ID of the plan to subscribe to
+                payment_method_id:
+                  type: string
+                  description: Stripe payment method ID
+      responses:
+        "200":
+          description: Subscription created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingSubscription"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/subscription/cancel:
+    post:
+      operationId: cancelSubscription
+      tags: [billing]
+      summary: Cancel the active subscription
+      description: "[cloud-only] Cancels the authenticated user's active subscription. The subscription remains active until the end of the current billing period."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Subscription cancelled
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingSubscription"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/subscription/resubscribe:
+    post:
+      operationId: resubscribe
+      tags: [billing]
+      summary: Resubscribe after cancellation
+      description: "[cloud-only] Reactivates a subscription that was previously cancelled but has not yet expired."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Subscription reactivated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingSubscription"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/topup:
+    post:
+      operationId: topUpCredits
+      tags: [billing]
+      summary: Purchase additional credits
+      description: "[cloud-only] Purchases a one-time credit top-up using the user's payment method on file."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - amount
+              properties:
+                amount:
+                  type: integer
+                  description: Number of credits to purchase
+      responses:
+        "200":
+          description: Top-up successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingBalance"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  # ---------------------------------------------------------------------------
+  # Workspace (cloud)
+  # ---------------------------------------------------------------------------
+  /api/workspace/api-keys:
+    get:
+      operationId: listWorkspaceApiKeys
+      tags: [workspace]
+      summary: List workspace API keys
+      description: "[cloud-only] Returns the list of API keys for the current workspace."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: API key list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/WorkspaceApiKey"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    post:
+      operationId: createWorkspaceApiKey
+      tags: [workspace]
+      summary: Create a workspace API key
+      description: "[cloud-only] Creates a new API key for the current workspace."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - name
+              properties:
+                name:
+                  type: string
+                  description: Display name for the API key
+      responses:
+        "201":
+          description: API key created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceApiKeyCreated"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspace/api-keys/{id}:
+    delete:
+      operationId: deleteWorkspaceApiKey
+      tags: [workspace]
+      summary: Delete a workspace API key
+      description: "[cloud-only] Revokes and deletes a workspace API key."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The API key ID.
+      responses:
+        "204":
+          description: API key deleted
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspace/invites:
+    get:
+      operationId: listWorkspaceInvites
+      tags: [workspace]
+      summary: List pending workspace invites
+      description: "[cloud-only] Returns the list of pending invitations for the current workspace."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Invite list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/WorkspaceInvite"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    post:
+      operationId: createWorkspaceInvite
+      tags: [workspace]
+      summary: Invite a user to the workspace
+      description: "[cloud-only] Creates an invitation for a user to join the current workspace."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - email
+              properties:
+                email:
+                  type: string
+                  format: email
+                  description: Email address to invite
+                role:
+                  type: string
+                  enum: [admin, member]
+                  description: Role to assign
+      responses:
+        "201":
+          description: Invite created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceInvite"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "409":
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspace/invites/{inviteId}:
+    delete:
+      operationId: deleteWorkspaceInvite
+      tags: [workspace]
+      summary: Cancel a workspace invite
+      description: "[cloud-only] Cancels a pending workspace invitation."
+      x-runtime: [cloud]
+      parameters:
+        - name: inviteId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The invite ID.
+      responses:
+        "204":
+          description: Invite cancelled
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspace/leave:
+    post:
+      operationId: leaveWorkspace
+      tags: [workspace]
+      summary: Leave the current workspace
+      description: "[cloud-only] Removes the authenticated user from the current workspace."
+      x-runtime: [cloud]
+      responses:
+        "204":
+          description: Left workspace
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspace/members:
+    get:
+      operationId: listWorkspaceMembers
+      tags: [workspace]
+      summary: List workspace members
+      description: "[cloud-only] Returns the list of members in the current workspace."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Member list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/WorkspaceMember"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspace/members/{user_id}/api-keys:
+    get:
+      operationId: listMemberApiKeys
+      tags: [workspace]
+      summary: List API keys for a workspace member
+      description: "[cloud-only] Returns the API keys belonging to a specific workspace member. Requires admin role."
+      x-runtime: [cloud]
+      parameters:
+        - name: user_id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The member's user ID.
+      responses:
+        "200":
+          description: API key list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/WorkspaceApiKey"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    delete:
+      operationId: bulkRevokeMemberApiKeys
+      tags: [workspace]
+      summary: Bulk revoke a member's API keys
+      description: "[cloud-only] Revokes all active API keys for a specific workspace member. Only workspace owners can perform this action."
+      x-runtime: [cloud]
+      parameters:
+        - name: user_id
+          in: path
+          required: true
+          schema:
+            type: string
+            minLength: 1
+          description: The member's user ID.
+      responses:
+        "200":
+          description: Keys revoked
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BulkRevokeAPIKeysResponse"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden — must be workspace owner
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspace/members/{userId}:
+    patch:
+      operationId: updateWorkspaceMember
+      tags: [workspace]
+      summary: Update a workspace member's role
+      description: "[cloud-only] Updates the role of a workspace member. Requires admin role."
+      x-runtime: [cloud]
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The member's user ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - role
+              properties:
+                role:
+                  type: string
+                  enum: [admin, member]
+                  description: New role to assign
+      responses:
+        "200":
+          description: Member updated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceMember"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    delete:
+      operationId: removeWorkspaceMember
+      tags: [workspace]
+      summary: Remove a member from the workspace
+      description: "[cloud-only] Removes a member from the current workspace. Requires admin role."
+      x-runtime: [cloud]
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The member's user ID.
+      responses:
+        "204":
+          description: Member removed
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspaces:
+    get:
+      operationId: listWorkspaces
+      tags: [workspace]
+      summary: List workspaces the user belongs to
+      description: "[cloud-only] Returns the list of workspaces the authenticated user is a member of."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Workspace list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Workspace"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    post:
+      operationId: createWorkspace
+      tags: [workspace]
+      summary: Create a new workspace
+      description: "[cloud-only] Creates a new workspace. The authenticated user becomes the owner."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - name
+              properties:
+                name:
+                  type: string
+                  description: Workspace name
+      responses:
+        "201":
+          description: Workspace created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Workspace"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspaces/{id}:
+    get:
+      operationId: getWorkspace
+      tags: [workspace]
+      summary: Get a workspace by ID
+      description: "[cloud-only] Returns details of a workspace the user is a member of."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The workspace ID.
+      responses:
+        "200":
+          description: Workspace detail
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Workspace"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    patch:
+      operationId: updateWorkspace
+      tags: [workspace]
+      summary: Update workspace settings
+      description: "[cloud-only] Updates the name or settings of a workspace. Requires admin role."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The workspace ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                  description: New workspace name
+      responses:
+        "200":
+          description: Workspace updated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Workspace"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    delete:
+      operationId: deleteWorkspace
+      tags: [workspace]
+      summary: Delete a workspace
+      description: "[cloud-only] Soft-deletes a workspace. Requires owner role. Personal workspaces cannot be deleted."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The workspace ID.
+      responses:
+        "204":
+          description: Workspace deleted
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden — must be workspace owner
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  # ---------------------------------------------------------------------------
+  # User / settings / misc (cloud)
+  # ---------------------------------------------------------------------------
+  /api/feedback:
+    post:
+      operationId: submitFeedback
+      tags: [user]
+      summary: Submit user feedback
+      description: "[cloud-only] Submits feedback from the user about their experience with the cloud runtime."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - message
+              properties:
+                message:
+                  type: string
+                  description: Feedback message
+                rating:
+                  type: integer
+                  minimum: 1
+                  maximum: 5
+                  description: Optional satisfaction rating
+                context:
+                  type: object
+                  additionalProperties: true
+                  description: Additional context metadata
+      responses:
+        "200":
+          description: Feedback submitted
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                  status:
+                    type: string
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/files/mask-layers:
+    get:
+      operationId: getMaskLayers
+      tags: [assets]
+      summary: Get related mask layer filenames
+      description: "[cloud-only] Given a mask file (any of the 4 layers), returns all related mask layer filenames. Used by the mask editor to load the paint, mask, and painted layers when reopening a previously edited mask."
+      x-runtime: [cloud]
+      parameters:
+        - name: filename
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Hash filename of any mask layer file
+      responses:
+        "200":
+          description: Related mask layers
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  mask:
+                    type: string
+                    description: Filename of the mask layer
+                    nullable: true
+                  paint:
+                    type: string
+                    description: Filename of the paint strokes layer
+                    nullable: true
+                  painted:
+                    type: string
+                    description: Filename of the painted image layer
+                    nullable: true
+                  painted_masked:
+                    type: string
+                    description: Filename of the final composite layer
+                    nullable: true
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: File not found or not a mask file
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/internal/cloud_analytics:
+    post:
+      operationId: postCloudAnalytics
+      tags: [internal]
+      summary: Post client analytics events
+      description: "[cloud-only] Receives analytics events from the frontend for processing by the cloud analytics pipeline."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - events
+              properties:
+                events:
+                  type: array
+                  items:
+                    type: object
+                    required:
+                      - event_name
+                    properties:
+                      event_name:
+                        type: string
+                      timestamp:
+                        type: string
+                        format: date-time
+                      properties:
+                        type: object
+                        additionalProperties: true
+      responses:
+        "200":
+          description: Events accepted
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/invites/{token}/accept:
+    post:
+      operationId: acceptInvite
+      tags: [workspace]
+      summary: Accept a workspace invitation
+      description: "[cloud-only] Accepts a workspace invitation using the invite token. The authenticated user is added to the workspace."
+      x-runtime: [cloud]
+      parameters:
+        - name: token
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The invitation token.
+      responses:
+        "200":
+          description: Invite accepted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Workspace"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/secrets:
+    get:
+      operationId: listSecrets
+      tags: [settings]
+      summary: List user secrets
+      description: "[cloud-only] Returns the list of secrets (API keys for third-party services) stored for the authenticated user. Secret values are redacted."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Secret list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/SecretMeta"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    post:
+      operationId: createSecret
+      tags: [settings]
+      summary: Create or update a secret
+      description: "[cloud-only] Stores a new secret or updates an existing one. Secrets are encrypted at rest."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - name
+                - value
+              properties:
+                name:
+                  type: string
+                  description: Secret name (unique per user)
+                value:
+                  type: string
+                  description: Secret value
+      responses:
+        "201":
+          description: Secret created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SecretMeta"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/secrets/{id}:
+    get:
+      operationId: getSecret
+      tags: [settings]
+      summary: Get secret metadata
+      description: "[cloud-only] Returns metadata for a specific secret. Does not return the plaintext secret value."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The secret ID.
+      responses:
+        "200":
+          description: Secret metadata
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SecretMeta"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    patch:
+      operationId: updateSecret
+      tags: [settings]
+      summary: Update a secret
+      description: "[cloud-only] Updates an existing secret's name and/or value. Both fields are optional; only provided fields are updated."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The secret ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdateSecretRequest"
+      responses:
+        "200":
+          description: Secret updated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SecretMeta"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "409":
+          description: Conflict — a secret with this name already exists
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    delete:
+      operationId: deleteSecret
+      tags: [settings]
+      summary: Delete a secret
+      description: "[cloud-only] Permanently deletes a stored secret."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The secret ID.
+      responses:
+        "204":
+          description: Secret deleted
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/user:
+    get:
+      operationId: getCloudUser
+      tags: [user]
+      summary: Get the authenticated cloud user
+      description: "[cloud-only] Returns the profile and account information for the currently authenticated user."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: User profile
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudUser"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    put:
+      operationId: updateCloudUser
+      tags: [user]
+      summary: Update the authenticated cloud user profile
+      description: "[cloud-only] Updates the profile information for the currently authenticated user."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                display_name:
+                  type: string
+                avatar_url:
+                  type: string
+                  format: uri
+      responses:
+        "200":
+          description: Updated profile
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudUser"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/userdata/{file}/publish:
+    get:
+      operationId: getUserdataFilePublish
+      tags: [userdata]
+      summary: Get publish info for a userdata file
+      description: "[cloud-only] Returns the publish status and share info for a userdata workflow file."
+      x-runtime: [cloud]
+      parameters:
+        - name: file
+          in: path
+          required: true
+          schema:
+            type: string
+          description: File path relative to user data directory
+      responses:
+        "200":
+          description: Publish info (publish_time is null if never published)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkflowPublishInfo"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Workflow not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    post:
+      operationId: publishUserdataFile
+      tags: [userdata]
+      summary: Publish a userdata file to the cloud
+      description: "[cloud-only] Makes a userdata file available via a public URL for sharing or embedding."
+      x-runtime: [cloud]
+      parameters:
+        - name: file
+          in: path
+          required: true
+          schema:
+            type: string
+          description: File path relative to user data directory
+      responses:
+        "200":
+          description: Published file URL
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  url:
+                    type: string
+                    format: uri
+                    description: Public URL of the published file
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/vhs/queryvideo:
+    get:
+      operationId: queryVhsVideo
+      tags: [view]
+      summary: Query VHS video metadata
+      description: "[cloud-only] Returns metadata about a video file processed by the VHS (Video Helper Suite) integration."
+      x-runtime: [cloud]
+      parameters:
+        - name: filename
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Video filename
+        - name: type
+          in: query
+          schema:
+            type: string
+            enum: [input, output, temp]
+          description: Directory type
+        - name: subfolder
+          in: query
+          schema:
+            type: string
+          description: Subfolder within the directory
+      responses:
+        "200":
+          description: Video metadata
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/vhs/viewaudio:
+    get:
+      operationId: viewVhsAudio
+      tags: [view]
+      summary: View or download VHS audio
+      description: "[cloud-only] Returns audio content from a VHS-processed file."
+      x-runtime: [cloud]
+      parameters:
+        - name: filename
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Audio filename
+        - name: type
+          in: query
+          schema:
+            type: string
+            enum: [input, output, temp]
+          description: Directory type
+        - name: subfolder
+          in: query
+          schema:
+            type: string
+          description: Subfolder within the directory
+      responses:
+        "200":
+          description: Audio content
+          content:
+            audio/*:
+              schema:
+                type: string
+                format: binary
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/vhs/viewvideo:
+    get:
+      operationId: viewVhsVideo
+      tags: [view]
+      summary: View or download VHS video
+      description: "[cloud-only] Returns video content from a VHS-processed file."
+      x-runtime: [cloud]
+      parameters:
+        - name: filename
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Video filename
+        - name: type
+          in: query
+          schema:
+            type: string
+            enum: [input, output, temp]
+          description: Directory type
+        - name: subfolder
+          in: query
+          schema:
+            type: string
+          description: Subfolder within the directory
+      responses:
+        "200":
+          description: Video content
+          content:
+            video/*:
+              schema:
+                type: string
+                format: binary
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/viewvideo:
+    get:
+      operationId: viewVideo
+      tags: [view]
+      summary: View or download a video file
+      description: "[cloud-only] Serves a video file from the output directory. Used by the frontend video player."
+      x-runtime: [cloud]
+      parameters:
+        - name: filename
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Video filename
+        - name: type
+          in: query
+          schema:
+            type: string
+            enum: [input, output, temp]
+          description: Directory type
+        - name: subfolder
+          in: query
+          schema:
+            type: string
+          description: Subfolder within the directory
+      responses:
+        "200":
+          description: Video content
+          content:
+            video/*:
+              schema:
+                type: string
+                format: binary
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/tasks:
+    get:
+      operationId: listTasks
+      tags: [task]
+      summary: List background tasks
+      description: "[cloud-only] Retrieve a paginated list of background tasks for the authenticated user. Supports filtering by task type, status, and creation time."
+      x-runtime: [cloud]
+      parameters:
+        - name: task_name
+          in: query
+          schema:
+            type: string
+          description: Filter by task type name (exact match).
+        - name: idempotency_key
+          in: query
+          schema:
+            type: string
+          description: Filter by idempotency key (exact match).
+        - name: status
+          in: query
+          schema:
+            type: string
+          description: Filter by one or more statuses (comma-separated).
+        - name: created_after
+          in: query
+          schema:
+            type: string
+            format: date-time
+          description: Filter tasks created after this timestamp.
+        - name: created_before
+          in: query
+          schema:
+            type: string
+            format: date-time
+          description: Filter tasks created before this timestamp.
+        - name: sort_order
+          in: query
+          schema:
+            type: string
+            enum: [asc, desc]
+            default: desc
+          description: Sort direction by create_time.
+        - name: offset
+          in: query
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+          description: Pagination offset (0-based).
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+          description: Maximum items per page (1-100).
+      responses:
+        "200":
+          description: Tasks retrieved
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TasksListResponse"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/tasks/{task_id}:
+    get:
+      operationId: getTask
+      tags: [task]
+      summary: Get task details
+      description: "[cloud-only] Retrieve full details for a specific background task."
+      x-runtime: [cloud]
+      parameters:
+        - name: task_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: Task identifier (UUID).
+      responses:
+        "200":
+          description: Task details
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TaskResponse"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Task not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+
 components:
   parameters:
     ComfyUserHeader:
@@ -2823,14 +6279,29 @@ components:
         name:
           type: string
           description: Name of the asset file
+        hash:
+          type: string
+          nullable: true
+          description: Blake3 content hash of the asset (preferred over asset_hash)
+          pattern: "^blake3:[a-f0-9]{64}$"
         asset_hash:
           type: string
-          description: Blake3 hash of the asset content
+          nullable: true
+          deprecated: true
+          description: "Deprecated: use `hash` instead. Blake3 hash of the asset content."
           pattern: "^blake3:[a-f0-9]{64}$"
         size:
           type: integer
           format: int64
           description: Size of the asset in bytes
+        width:
+          type: integer
+          nullable: true
+          description: "Original image width in pixels. Null for non-image assets or assets ingested before dimension extraction."
+        height:
+          type: integer
+          nullable: true
+          description: "Original image height in pixels. Null for non-image assets or assets ingested before dimension extraction."
         mime_type:
           type: string
           description: MIME type of the asset
@@ -2859,7 +6330,14 @@ components:
         prompt_id:
           type: string
           format: uuid
-          description: ID of the prompt that created this asset
+          nullable: true
+          deprecated: true
+          description: "Deprecated: use job_id instead. ID of the prompt that created this asset."
+        job_id:
+          type: string
+          format: uuid
+          nullable: true
+          description: ID of the job that created this asset
         created_at:
           type: string
           format: date-time
@@ -2897,8 +6375,16 @@ components:
           format: uuid
         name:
           type: string
+        hash:
+          type: string
+          nullable: true
+          description: Blake3 content hash of the asset (preferred over asset_hash)
+          pattern: "^blake3:[a-f0-9]{64}$"
         asset_hash:
           type: string
+          nullable: true
+          deprecated: true
+          description: "Deprecated: use `hash` instead. Blake3 hash of the asset content."
           pattern: "^blake3:[a-f0-9]{64}$"
         tags:
           type: array
@@ -2909,6 +6395,17 @@ components:
         user_metadata:
           type: object
           additionalProperties: true
+        prompt_id:
+          type: string
+          format: uuid
+          nullable: true
+          deprecated: true
+          description: "Deprecated: use job_id instead. ID of the prompt that created this asset."
+        job_id:
+          type: string
+          format: uuid
+          nullable: true
+          description: ID of the job that created this asset
         updated_at:
           type: string
           format: date-time
@@ -3365,3 +6862,1218 @@ components:
           enum: [created, running, completed, failed]
         error:
           type: string
+
+
+    # -------------------------------------------------------------------
+    # Cloud-runtime schemas
+    #
+    # These schemas are exclusively referenced by cloud-runtime operations.
+    # Tagged x-runtime: [cloud].
+    # -------------------------------------------------------------------
+    CloudError:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Standard error response from cloud endpoints."
+      required:
+        - error
+      properties:
+        error:
+          type: string
+          description: Error message
+        code:
+          type: string
+          description: Machine-readable error code
+        details:
+          type: object
+          additionalProperties: true
+          description: Additional error context
+
+    CloudJobStatus:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Status of a cloud job."
+      required:
+        - id
+        - status
+      properties:
+        id:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [pending, running, completed, failed, cancelled]
+        progress:
+          type: number
+          minimum: 0
+          maximum: 1
+          description: "Execution progress (0.0 to 1.0)"
+        started_at:
+          type: string
+          format: date-time
+          nullable: true
+        completed_at:
+          type: string
+          format: date-time
+          nullable: true
+
+    CloudPrompt:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A cloud-executed prompt record."
+      required:
+        - id
+        - status
+      properties:
+        id:
+          type: string
+          format: uuid
+        status:
+          type: string
+        workflow:
+          type: object
+          additionalProperties: true
+        outputs:
+          type: object
+          additionalProperties: true
+        created_at:
+          type: string
+          format: date-time
+        completed_at:
+          type: string
+          format: date-time
+          nullable: true
+
+    HistoryV2Response:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Paginated execution history in v2 format."
+      required:
+        - items
+        - total
+        - has_more
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/HistoryV2Entry"
+        total:
+          type: integer
+        has_more:
+          type: boolean
+
+    HistoryV2Entry:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A single execution history entry in v2 format."
+      required:
+        - id
+        - status
+      properties:
+        id:
+          type: string
+          format: uuid
+        status:
+          type: string
+        workflow:
+          type: object
+          additionalProperties: true
+        outputs:
+          type: object
+          additionalProperties: true
+        created_at:
+          type: string
+          format: date-time
+        started_at:
+          type: string
+          format: date-time
+          nullable: true
+        completed_at:
+          type: string
+          format: date-time
+          nullable: true
+        preview_output:
+          type: object
+          additionalProperties: true
+
+    CloudLogsResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Paginated cloud execution logs."
+      required:
+        - entries
+      properties:
+        entries:
+          type: array
+          items:
+            type: object
+            properties:
+              timestamp:
+                type: string
+                format: date-time
+              level:
+                type: string
+                enum: [debug, info, warn, error]
+              message:
+                type: string
+              job_id:
+                type: string
+                format: uuid
+        total:
+          type: integer
+        has_more:
+          type: boolean
+
+    AssetDownloadRequest:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A single asset to download to the cloud runtime."
+      required:
+        - asset_id
+      properties:
+        asset_id:
+          type: string
+          format: uuid
+          description: ID of the asset to download
+        target_path:
+          type: string
+          description: Target path on the runtime filesystem
+
+    AssetImportRequest:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A single asset to import from an external URL."
+      required:
+        - url
+      properties:
+        url:
+          type: string
+          format: uri
+          description: URL of the asset to import
+        name:
+          type: string
+          description: Display name for the imported asset
+        tags:
+          type: array
+          items:
+            type: string
+
+    RemoteAssetMetadata:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Metadata fetched from a remote asset URL."
+      properties:
+        content_type:
+          type: string
+          description: MIME type of the remote file
+        content_length:
+          type: integer
+          format: int64
+          description: Size in bytes
+        filename:
+          type: string
+          description: Suggested filename from Content-Disposition or URL
+
+    CloudNode:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] An installed custom node package in the cloud runtime."
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        version:
+          type: string
+        description:
+          type: string
+        author:
+          type: string
+        repository:
+          type: string
+          format: uri
+        installed_at:
+          type: string
+          format: date-time
+        enabled:
+          type: boolean
+
+    CloudNodeList:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Paginated list of installed custom node packages."
+      required:
+        - nodes
+      properties:
+        nodes:
+          type: array
+          items:
+            $ref: "#/components/schemas/CloudNode"
+        total:
+          type: integer
+        has_more:
+          type: boolean
+
+    HubLabel:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A label/category used for tagging hub content."
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        description:
+          type: string
+        color:
+          type: string
+          description: Hex color code for the label
+
+    HubProfile:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A public user profile on the ComfyUI Hub."
+      required:
+        - username
+      properties:
+        username:
+          type: string
+        display_name:
+          type: string
+        bio:
+          type: string
+        avatar_url:
+          type: string
+          format: uri
+        links:
+          type: array
+          items:
+            type: string
+            format: uri
+        workflow_count:
+          type: integer
+        created_at:
+          type: string
+          format: date-time
+
+    HubWorkflow:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A published workflow on the ComfyUI Hub."
+      required:
+        - share_id
+        - name
+      properties:
+        share_id:
+          type: string
+        name:
+          type: string
+        description:
+          type: string
+        author:
+          $ref: "#/components/schemas/HubProfile"
+        labels:
+          type: array
+          items:
+            $ref: "#/components/schemas/HubLabel"
+        thumbnail_url:
+          type: string
+          format: uri
+        content:
+          type: object
+          additionalProperties: true
+          description: Workflow graph JSON
+        likes:
+          type: integer
+        views:
+          type: integer
+        forks:
+          type: integer
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    HubWorkflowList:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Paginated list of hub workflows."
+      required:
+        - workflows
+        - total
+        - has_more
+      properties:
+        workflows:
+          type: array
+          items:
+            $ref: "#/components/schemas/HubWorkflow"
+        total:
+          type: integer
+        has_more:
+          type: boolean
+
+    HubWorkflowIndexEntry:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Lightweight entry in the hub workflow index for client-side search."
+      required:
+        - share_id
+        - name
+      properties:
+        share_id:
+          type: string
+        name:
+          type: string
+        author_username:
+          type: string
+        labels:
+          type: array
+          items:
+            type: string
+        likes:
+          type: integer
+        updated_at:
+          type: string
+          format: date-time
+
+    CloudWorkflow:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A cloud-managed workflow with version history."
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        description:
+          type: string
+        share_id:
+          type: string
+          nullable: true
+          description: Public share identifier if published
+        latest_version_id:
+          type: string
+          format: uuid
+          nullable: true
+        thumbnail_url:
+          type: string
+          format: uri
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    CloudWorkflowList:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Paginated list of cloud workflows."
+      required:
+        - workflows
+        - total
+        - has_more
+      properties:
+        workflows:
+          type: array
+          items:
+            $ref: "#/components/schemas/CloudWorkflow"
+        total:
+          type: integer
+        has_more:
+          type: boolean
+
+    CloudWorkflowVersion:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A version of a cloud workflow."
+      required:
+        - id
+        - workflow_id
+      properties:
+        id:
+          type: string
+          format: uuid
+        workflow_id:
+          type: string
+          format: uuid
+        version_number:
+          type: integer
+        created_at:
+          type: string
+          format: date-time
+
+    AuthSession:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Current authentication session state."
+      required:
+        - user
+      properties:
+        user:
+          $ref: "#/components/schemas/CloudUser"
+        workspace:
+          $ref: "#/components/schemas/Workspace"
+        expires_at:
+          type: string
+          format: date-time
+
+    AuthTokenResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] OAuth2 token response."
+      required:
+        - access_token
+        - token_type
+      properties:
+        access_token:
+          type: string
+        token_type:
+          type: string
+          description: Always "Bearer"
+        expires_in:
+          type: integer
+          description: Token lifetime in seconds
+        refresh_token:
+          type: string
+          nullable: true
+        scope:
+          type: string
+
+    JwksResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] JSON Web Key Set for JWT verification."
+      required:
+        - keys
+      properties:
+        keys:
+          type: array
+          items:
+            type: object
+            required:
+              - kty
+              - kid
+              - use
+            properties:
+              kty:
+                type: string
+                description: Key type (e.g. RSA)
+              kid:
+                type: string
+                description: Key ID
+              use:
+                type: string
+                description: Key use (e.g. sig)
+              alg:
+                type: string
+                description: Algorithm (e.g. RS256)
+              n:
+                type: string
+                description: RSA modulus (base64url)
+              e:
+                type: string
+                description: RSA exponent (base64url)
+            additionalProperties: true
+
+    BillingBalance:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Current credit balance and usage summary."
+      required:
+        - credits_remaining
+      properties:
+        credits_remaining:
+          type: integer
+          description: Available credits
+        credits_used:
+          type: integer
+          description: Credits used in current billing period
+        credits_total:
+          type: integer
+          description: Total credits allocated in current period
+
+    BillingEvent:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A billing event (charge, credit, refund)."
+      required:
+        - id
+        - type
+        - amount
+        - created_at
+      properties:
+        id:
+          type: string
+        type:
+          type: string
+          enum: [charge, credit, refund, topup, subscription]
+        amount:
+          type: integer
+          description: Amount in credits
+        description:
+          type: string
+        job_id:
+          type: string
+          format: uuid
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+
+    BillingEventList:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Paginated list of billing events."
+      required:
+        - events
+        - total
+        - has_more
+      properties:
+        events:
+          type: array
+          items:
+            $ref: "#/components/schemas/BillingEvent"
+        total:
+          type: integer
+        has_more:
+          type: boolean
+
+    BillingOp:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A billing operation record."
+      required:
+        - id
+        - status
+      properties:
+        id:
+          type: string
+        status:
+          type: string
+          enum: [pending, completed, failed]
+        type:
+          type: string
+        amount:
+          type: integer
+        created_at:
+          type: string
+          format: date-time
+        completed_at:
+          type: string
+          format: date-time
+          nullable: true
+
+    BillingPlan:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A subscription plan with pricing details."
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        description:
+          type: string
+        credits_per_month:
+          type: integer
+        price_cents:
+          type: integer
+          description: Monthly price in cents (USD)
+        currency:
+          type: string
+          default: usd
+        features:
+          type: array
+          items:
+            type: string
+          description: List of plan features
+
+    BillingStatus:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Overall billing and subscription status."
+      properties:
+        subscription:
+          $ref: "#/components/schemas/BillingSubscription"
+        balance:
+          $ref: "#/components/schemas/BillingBalance"
+        has_payment_method:
+          type: boolean
+
+    BillingSubscription:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Active subscription details."
+      required:
+        - id
+        - status
+        - plan_id
+      properties:
+        id:
+          type: string
+        status:
+          type: string
+          enum: [active, cancelled, past_due, trialing]
+        plan_id:
+          type: string
+        plan_name:
+          type: string
+        current_period_start:
+          type: string
+          format: date-time
+        current_period_end:
+          type: string
+          format: date-time
+        cancel_at_period_end:
+          type: boolean
+
+    SubscriptionPreview:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Preview of a subscription change including prorations."
+      properties:
+        plan_id:
+          type: string
+        plan_name:
+          type: string
+        amount_due:
+          type: integer
+          description: Amount due in cents
+        proration_amount:
+          type: integer
+          description: Proration adjustment in cents
+        currency:
+          type: string
+        next_billing_date:
+          type: string
+          format: date-time
+
+    Workspace:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A cloud workspace for team collaboration."
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        owner_id:
+          type: string
+        member_count:
+          type: integer
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    WorkspaceMember:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A member of a cloud workspace."
+      required:
+        - user_id
+        - role
+      properties:
+        user_id:
+          type: string
+        email:
+          type: string
+          format: email
+        display_name:
+          type: string
+        avatar_url:
+          type: string
+          format: uri
+        role:
+          type: string
+          enum: [owner, admin, member]
+        joined_at:
+          type: string
+          format: date-time
+
+    WorkspaceInvite:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A pending workspace invitation."
+      required:
+        - id
+        - email
+        - role
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+          format: email
+        role:
+          type: string
+          enum: [admin, member]
+        invited_by:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+        expires_at:
+          type: string
+          format: date-time
+
+    WorkspaceApiKey:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A workspace API key (secret value redacted)."
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        prefix:
+          type: string
+          description: First few characters of the key for identification
+        created_at:
+          type: string
+          format: date-time
+        last_used_at:
+          type: string
+          format: date-time
+          nullable: true
+        created_by:
+          type: string
+
+    WorkspaceApiKeyCreated:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A newly created workspace API key, including the full secret value (shown only once)."
+      required:
+        - id
+        - name
+        - key
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        key:
+          type: string
+          description: Full API key value (only returned on creation)
+        prefix:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+
+    CloudUser:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A cloud-authenticated user profile."
+      required:
+        - id
+        - email
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+          format: email
+        display_name:
+          type: string
+        avatar_url:
+          type: string
+          format: uri
+        created_at:
+          type: string
+          format: date-time
+
+    SecretMeta:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Metadata for a stored secret (value is never returned)."
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        provider:
+          type: string
+          description: "[cloud-only] Provider identifier (e.g., huggingface, civitai)."
+          x-runtime: [cloud]
+        last_used_at:
+          type: string
+          format: date-time
+          description: "[cloud-only] When the secret was last used for decryption."
+          x-runtime: [cloud]
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    UpdateSecretRequest:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Request body for updating an existing user secret."
+      properties:
+        name:
+          type: string
+          description: New name for the secret
+        secret_value:
+          type: string
+          description: New secret value (API key, token, etc.)
+
+    CreateSessionResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Response after creating a session cookie."
+      required:
+        - success
+      properties:
+        success:
+          type: boolean
+        expiresIn:
+          type: integer
+          description: Session expiration time in seconds.
+
+    DeleteSessionResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Response after deleting a session cookie."
+      required:
+        - success
+      properties:
+        success:
+          type: boolean
+
+    CreateHubProfileRequest:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Request body for creating a new Hub profile."
+      required:
+        - workspace_id
+        - username
+      properties:
+        workspace_id:
+          type: string
+        username:
+          type: string
+          description: Unique URL-safe slug. Immutable after creation.
+        display_name:
+          type: string
+        description:
+          type: string
+        avatar_token:
+          type: string
+        website_urls:
+          type: array
+          items:
+            type: string
+
+    PublishHubWorkflowRequest:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Request body for publishing or updating a workflow on the Hub."
+      required:
+        - username
+        - name
+        - workflow_filename
+        - asset_ids
+      properties:
+        username:
+          type: string
+        name:
+          type: string
+        workflow_filename:
+          type: string
+        asset_ids:
+          type: array
+          items:
+            type: string
+        description:
+          type: string
+        tags:
+          type: array
+          items:
+            type: string
+        models:
+          type: array
+          items:
+            type: string
+        custom_nodes:
+          type: array
+          items:
+            type: string
+        tutorial_url:
+          type: string
+        metadata:
+          type: object
+          additionalProperties: true
+        thumbnail_type:
+          type: string
+          enum: [image, video, image_comparison]
+        thumbnail_token_or_url:
+          type: string
+        thumbnail_comparison_token_or_url:
+          type: string
+        sample_image_tokens_or_urls:
+          type: array
+          items:
+            type: string
+
+    HubWorkflowDetail:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Full Hub workflow detail including versions, assets, and statistics."
+      required:
+        - share_id
+        - workflow_id
+        - name
+        - workflow_json
+        - assets
+        - profile
+        - status
+      properties:
+        share_id:
+          type: string
+        workflow_id:
+          type: string
+        name:
+          type: string
+        status:
+          type: string
+          enum: [pending, approved, rejected, deprecated]
+        description:
+          type: string
+        thumbnail_type:
+          type: string
+          enum: [image, video, image_comparison]
+        thumbnail_url:
+          type: string
+        thumbnail_comparison_url:
+          type: string
+        tutorial_url:
+          type: string
+        metadata:
+          type: object
+          additionalProperties: true
+        sample_image_urls:
+          type: array
+          items:
+            type: string
+        publish_time:
+          type: string
+          format: date-time
+          nullable: true
+        workflow_json:
+          type: object
+          additionalProperties: true
+        assets:
+          type: array
+          items:
+            $ref: "#/components/schemas/AssetInfo"
+        profile:
+          $ref: "#/components/schemas/HubProfile"
+
+    AssetInfo:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Lightweight asset reference used in workflow publishing payloads."
+      required:
+        - id
+        - filename
+      properties:
+        id:
+          type: string
+        filename:
+          type: string
+        mime_type:
+          type: string
+        size_bytes:
+          type: integer
+          format: int64
+
+    BulkRevokeAPIKeysResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Response after bulk-revoking API keys for a workspace member."
+      required:
+        - revoked_count
+      properties:
+        revoked_count:
+          type: integer
+          minimum: 0
+
+    CreateWorkflowVersionRequest:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Request body for creating a new version of a saved workflow."
+      required:
+        - base_version
+        - workflow_json
+      properties:
+        base_version:
+          type: integer
+          description: Version number this change is based on (for optimistic concurrency).
+        workflow_json:
+          type: object
+          additionalProperties: true
+
+    WorkflowVersionResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Metadata for a single workflow version."
+      required:
+        - id
+        - version
+        - latest_version
+        - created_by
+        - created_at
+      properties:
+        id:
+          type: string
+        version:
+          type: integer
+        latest_version:
+          type: integer
+        created_by:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+
+    WorkflowPublishInfo:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Publishing metadata for a workflow shared to the Hub."
+      required:
+        - workflow_id
+        - share_id
+        - listed
+        - assets
+      properties:
+        workflow_id:
+          type: string
+        share_id:
+          type: string
+        publish_time:
+          type: string
+          format: date-time
+          nullable: true
+        listed:
+          type: boolean
+        assets:
+          type: array
+          items:
+            $ref: "#/components/schemas/AssetInfo"
+
+    TaskEntry:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Task data for list views."
+      required:
+        - id
+        - task_name
+        - status
+        - create_time
+      properties:
+        id:
+          type: string
+          format: uuid
+        task_name:
+          type: string
+        status:
+          type: string
+          enum: [created, running, completed, failed]
+        create_time:
+          type: string
+          format: date-time
+        started_at:
+          type: string
+          format: date-time
+        completed_at:
+          type: string
+          format: date-time
+
+    TaskResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Full task details including payload and result."
+      required:
+        - id
+        - idempotency_key
+        - task_name
+        - payload
+        - status
+        - create_time
+        - update_time
+      properties:
+        id:
+          type: string
+          format: uuid
+        idempotency_key:
+          type: string
+        task_name:
+          type: string
+        payload:
+          type: object
+          additionalProperties: true
+        status:
+          type: string
+          enum: [created, running, completed, failed]
+        result:
+          type: object
+          additionalProperties: true
+        create_time:
+          type: string
+          format: date-time
+        update_time:
+          type: string
+          format: date-time
+        started_at:
+          type: string
+          format: date-time
+        completed_at:
+          type: string
+          format: date-time
+        error:
+          type: string
+
+    TasksListResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Paginated list of background tasks for the authenticated user."
+      required:
+        - tasks
+        - pagination
+      properties:
+        tasks:
+          type: array
+          items:
+            $ref: "#/components/schemas/TaskEntry"
+        pagination:
+          $ref: "#/components/schemas/PaginationInfo"
\ No newline at end of file

From 65045730a60af0bf75cec2a738555a952da2ea4e Mon Sep 17 00:00:00 2001
From: Alexander Piskun <13381981+bigcat88@users.noreply.github.com>
Date: Fri, 8 May 2026 23:11:52 +0300
Subject: [PATCH 06/10] [Partner Nodes] additionally use Baidu server to detect
 the accessibility of internet (#13803)

Signed-off-by: bigcat88 <bigcat88@icloud.com>
---
 comfy_api_nodes/util/client.py | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/comfy_api_nodes/util/client.py b/comfy_api_nodes/util/client.py
index 8e1ba91ba..052301c33 100644
--- a/comfy_api_nodes/util/client.py
+++ b/comfy_api_nodes/util/client.py
@@ -488,10 +488,30 @@ async def _diagnose_connectivity() -> dict[str, bool]:
         "api_accessible": False,
     }
     timeout = aiohttp.ClientTimeout(total=5.0)
+
+    # Probe Google and Baidu in parallel: Google is blocked by the GFW in mainland China, so a Baidu probe is required
+    # to correctly detect that Chinese users with working internet do have working internet.
+    internet_probe_urls = ("https://www.google.com", "https://www.baidu.com")
+
     async with aiohttp.ClientSession(timeout=timeout) as session:
-        with contextlib.suppress(ClientError, OSError):
-            async with session.get("https://www.google.com") as resp:
-                results["internet_accessible"] = resp.status < 500
+        async def _probe(url: str) -> bool:
+            try:
+                async with session.get(url) as resp:
+                    return resp.status < 500
+            except (ClientError, OSError, asyncio.TimeoutError):
+                return False
+
+        probe_tasks = [asyncio.create_task(_probe(u)) for u in internet_probe_urls]
+        try:
+            for fut in asyncio.as_completed(probe_tasks):
+                if await fut:
+                    results["internet_accessible"] = True
+                    break
+        finally:
+            for t in probe_tasks:
+                if not t.done():
+                    t.cancel()
+            await asyncio.gather(*probe_tasks, return_exceptions=True)
         if not results["internet_accessible"]:
             return results
 

From 66669b2ded7d8f362fdf64bb1c77a8df0f684e2f Mon Sep 17 00:00:00 2001
From: comfyanonymous <121283862+comfyanonymous@users.noreply.github.com>
Date: Fri, 8 May 2026 17:32:14 -0700
Subject: [PATCH 07/10] I don't think there was any because nobody complained.
 (#13807)

---
 comfy/utils.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/comfy/utils.py b/comfy/utils.py
index 7b7faad3a..91e1ba3d3 100644
--- a/comfy/utils.py
+++ b/comfy/utils.py
@@ -1390,7 +1390,7 @@ def convert_old_quants(state_dict, model_prefix="", metadata={}):
                     k_out = "{}.weight_scale".format(layer)
 
                 if layer is not None:
-                    layer_conf = {"format": "float8_e4m3fn"}  # TODO: check if anyone did some non e4m3fn scaled checkpoints
+                    layer_conf = {"format": "float8_e4m3fn"}
                     if full_precision_matrix_mult:
                         layer_conf["full_precision_matrix_mult"] = full_precision_matrix_mult
                     layers[layer] = layer_conf

From 4e823431cc8291deced4fc2dcf3967be2549e4c0 Mon Sep 17 00:00:00 2001
From: Matt Miller <mattmiller@comfy.org>
Date: Fri, 8 May 2026 19:14:23 -0700
Subject: [PATCH 08/10] Add cloud-runtime experiment node-schema endpoints to
 spec (#13806)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Add cloud-runtime experiment node-schema endpoints to spec

Replace the GET operations at /api/experiment/nodes and
/api/experiment/nodes/{id} with getNodeInfoSchema and getNodeByID —
the optimized, ETag-tagged object_info schema endpoints the cloud
frontend depends on for the workflow editor.

Each operation is tagged x-runtime: [cloud] and uses the runtime-only
tag for cloud-side codegen exclusion. Response headers document the
ETag and Cache-Control validators; 304 Not Modified is declared for
RFC 7232 conditional GETs.

Remove the now-unused CloudNodeList schema to keep Spectral clean.

Co-authored-by: Matt Miller <MillerMedia@users.noreply.github.com>

* spec: document If-None-Match header on conditional GET endpoints

Both `getNodeInfoSchema` and `getNodeByID` advertise `ETag` response
headers and a `304 Not Modified` response, but the spec didn't declare
the `If-None-Match` request header that triggers conditional validation.
Adding it as an optional header parameter on both ops so client codegen
exposes the conditional-GET pattern.
---
 openapi.yaml | 106 +++++++++++++++++++++++++--------------------------
 1 file changed, 51 insertions(+), 55 deletions(-)

diff --git a/openapi.yaml b/openapi.yaml
index 4216c1a6c..d4c9e67ca 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -74,6 +74,8 @@ tags:
     description: Cloud workflow management and versioning (cloud-only)
   - name: task
     description: Background task management (cloud-only)
+  - name: runtime-only
+    description: Operations served exclusively by the cloud runtime with no local equivalent
 
 paths:
   # ---------------------------------------------------------------------------
@@ -2573,35 +2575,38 @@ paths:
   # ---------------------------------------------------------------------------
   /api/experiment/nodes:
     get:
-      operationId: listCloudNodes
-      tags: [node]
-      summary: List installed custom nodes
-      description: "[cloud-only] Returns the list of custom node packages installed in the cloud runtime."
+      operationId: getNodeInfoSchema
+      tags: [runtime-only]
+      summary: Get pre-rendered node info schema
+      description: "[cloud-only] Returns the static ComfyUI object_info schema, identical for every caller, rendered once at startup with empty model/user-file context. Served by a raw HTTP handler that writes pre-rendered bytes with ETag + Cache-Control validators for RFC 7232 conditional GETs."
       x-runtime: [cloud]
       parameters:
-        - name: limit
-          in: query
+        - name: If-None-Match
+          in: header
+          required: false
           schema:
-            type: integer
-          description: Maximum number of results
-        - name: offset
-          in: query
-          schema:
-            type: integer
-          description: Pagination offset
+            type: string
+          description: Entity tag previously returned by this endpoint. When present and matching, the server returns 304 Not Modified.
       responses:
         "200":
-          description: Custom node list
+          description: Node info schema
+          headers:
+            ETag:
+              schema:
+                type: string
+              description: Entity tag for conditional request validation
+            Cache-Control:
+              schema:
+                type: string
+              description: Cache directives for the response
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/CloudNodeList"
-        "401":
-          description: Unauthorized
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/CloudError"
+                type: object
+                additionalProperties:
+                  $ref: "#/components/schemas/NodeInfo"
+        "304":
+          description: Not Modified — returned when the client sends a matching If-None-Match header
     post:
       operationId: installCloudNode
       tags: [node]
@@ -2651,10 +2656,10 @@ paths:
 
   /api/experiment/nodes/{id}:
     get:
-      operationId: getCloudNode
-      tags: [node]
-      summary: Get details of an installed custom node
-      description: "[cloud-only] Returns details about a specific installed custom node package."
+      operationId: getNodeByID
+      tags: [runtime-only]
+      summary: Get a single node definition by ID
+      description: "[cloud-only] Returns one node's definition from the pre-indexed object_info schema. Served by a raw HTTP handler that writes pre-rendered bytes with ETag + Cache-Control validators for RFC 7232 conditional GETs."
       x-runtime: [cloud]
       parameters:
         - name: id
@@ -2662,26 +2667,33 @@ paths:
           required: true
           schema:
             type: string
-          description: Custom node package ID
+          description: Node class identifier
+        - name: If-None-Match
+          in: header
+          required: false
+          schema:
+            type: string
+          description: Entity tag previously returned by this endpoint. When present and matching, the server returns 304 Not Modified.
       responses:
         "200":
-          description: Node detail
+          description: Single node definition
+          headers:
+            ETag:
+              schema:
+                type: string
+              description: Entity tag for conditional request validation
+            Cache-Control:
+              schema:
+                type: string
+              description: Cache directives for the response
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/CloudNode"
-        "401":
-          description: Unauthorized
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/CloudError"
+                $ref: "#/components/schemas/NodeInfo"
+        "304":
+          description: Not Modified — returned when the client sends a matching If-None-Match header
         "404":
-          description: Not found
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/CloudError"
+          description: Node not found
     delete:
       operationId: uninstallCloudNode
       tags: [node]
@@ -7100,22 +7112,6 @@ components:
         enabled:
           type: boolean
 
-    CloudNodeList:
-      type: object
-      x-runtime: [cloud]
-      description: "[cloud-only] Paginated list of installed custom node packages."
-      required:
-        - nodes
-      properties:
-        nodes:
-          type: array
-          items:
-            $ref: "#/components/schemas/CloudNode"
-        total:
-          type: integer
-        has_more:
-          type: boolean
-
     HubLabel:
       type: object
       x-runtime: [cloud]

From 8b08bfdcbe2b4cd8f4426bd1111aaf17b118e33d Mon Sep 17 00:00:00 2001
From: lin-bot23 <linzhixiong23@gmail.com>
Date: Sat, 9 May 2026 12:26:13 +0900
Subject: [PATCH 09/10] Add description field to blueprint subgraphs (#13797)

* Add description field to all blueprint subgraphs

Sets the 'description' field on every subgraph blueprint node,
which will show on the node preview and tooltip. Covers all 51
blueprint files under blueprints/.

* Update blueprint descriptions with researched model info

* Refine blueprint descriptions with researched model specs from docs

Updates subgraph descriptions across all 51 blueprints with accurate
model details drawn from ComfyUI docs, including:
- Flux.1 Dev: 12B open-weights, Pro-level quality
- Flux.2 Klein 4B: fastest Flux, distilled architecture
- Qwen-Image: 20B MMDiT, multilingual text rendering
- Z-Image-Turbo: distilled 6B DiT, sub-second inference
- LTX-2/2.3: 19B DiT audio-video foundation model
- Wan2.2: open-source, 14B/1.3B variants
- ACE-Step 1.5: ~1s full-song generation
- GPU shader nodes consistently labeled as fragment shaders

* Strip marketing fluff and license info from descriptions

* Fix Canny to Video (LTX 2.0) description

* Remove 'local-' prefix from subgraph names

* Preserve UTF-8 encoding in JSON files (ensure_ascii=False)

* Apply review suggestions from alexisrolland

- Rename 'Image to Model (Hunyuan3d 2.1)' -> 'Image to 3D Model (Hunyuan3d 2.1)'
- Rename 'Image Upscale(Z-image-Turbo)' -> 'Image Upscale (Z-image-Turbo)'
- Rename 'Video Inpaint(Wan2.1 VACE)' -> 'Video Inpaint (Wan 2.1 VACE)'
- Use 'Black Forest Labs' branding in Flux descriptions
- Use 'Google's Gemini' with possessive in captioning nodes
- Normalize 'Wan 2.2' and 'Wan 2.1' spacing in descriptions

* fix: revert Color Adjustment.json to preserve original GLSL shader content

Only adds the 'description' field without modifying the shader code
(which contained Unicode escape \\u2192 that should be preserved).

* Apply CodeRabbit review suggestions

- Color Adjustment: include vibrance in description
- Image Blur: expand to Gaussian/Box/Radial modes
- Flux.2 Klein 4B: narrow to image edit only (no T2I)
- NetaYume Lumina: correct model base (Neta Lumina, not Lumina-Next)

---------

Co-authored-by: linmoumou <linmoumou@linmoumoudeMac-mini.local>
Co-authored-by: Daxiong (Lin) <contact@comfyui-wiki.com>
---
 blueprints/Brightness and Contrast.json             | 5 +++--
 blueprints/Canny to Image (Z-Image-Turbo).json      | 7 ++++---
 blueprints/Canny to Video (LTX 2.0).json            | 7 ++++---
 blueprints/Chromatic Aberration.json                | 5 +++--
 blueprints/Color Adjustment.json                    | 3 ++-
 blueprints/Color Balance.json                       | 3 ++-
 blueprints/Color Curves.json                        | 3 ++-
 blueprints/Crop Images 2x2.json                     | 3 ++-
 blueprints/Crop Images 3x3.json                     | 3 ++-
 blueprints/Depth to Image (Z-Image-Turbo).json      | 6 ++++--
 blueprints/Depth to Video (ltx 2.0).json            | 6 ++++--
 blueprints/Edge-Preserving Blur.json                | 5 +++--
 blueprints/Film Grain.json                          | 5 +++--
 blueprints/First-Last-Frame to Video (LTX-2.3).json | 3 ++-
 blueprints/Glow.json                                | 5 +++--
 blueprints/Hue and Saturation.json                  | 5 +++--
 blueprints/Image Blur.json                          | 3 ++-
 blueprints/Image Captioning (gemini).json           | 3 ++-
 blueprints/Image Channels.json                      | 5 +++--
 blueprints/Image Edit (FireRed Image Edit 1.1).json | 3 ++-
 blueprints/Image Edit (Flux.2 Klein 4B).json        | 8 +++++---
 blueprints/Image Edit (LongCat Image Edit).json     | 3 ++-
 blueprints/Image Edit (Qwen 2511).json              | 7 ++++---
 blueprints/Image Inpainting (Flux.1 Fill Dev).json  | 5 +++--
 blueprints/Image Inpainting (Qwen-image).json       | 6 ++++--
 blueprints/Image Levels.json                        | 5 +++--
 blueprints/Image Outpainting (Qwen-Image).json      | 9 ++++++---
 blueprints/Image Upscale(Z-image-Turbo).json        | 5 +++--
 blueprints/Image to Depth Map (Lotus).json          | 7 ++++---
 blueprints/Image to Layers(Qwen-Image-Layered).json | 3 ++-
 blueprints/Image to Model (Hunyuan3d 2.1).json      | 5 +++--
 blueprints/Image to Video (LTX-2.3).json            | 3 ++-
 blueprints/Image to Video (Wan 2.2).json            | 5 +++--
 blueprints/Pose to Image (Z-Image-Turbo).json       | 7 ++++---
 blueprints/Pose to Video (LTX 2.0).json             | 3 ++-
 blueprints/Prompt Enhance.json                      | 5 +++--
 blueprints/Sharpen.json                             | 5 +++--
 blueprints/Text to Audio (ACE-Step 1.5).json        | 7 ++++---
 blueprints/Text to Image (Flux.1 Dev).json          | 5 +++--
 blueprints/Text to Image (Flux.1 Krea Dev).json     | 5 +++--
 blueprints/Text to Image (NetaYume Lumina).json     | 8 +++++---
 blueprints/Text to Image (Qwen-Image 2512).json     | 3 ++-
 blueprints/Text to Image (Qwen-Image).json          | 3 ++-
 blueprints/Text to Image (Z-Image-Turbo).json       | 7 ++++---
 blueprints/Text to Video (LTX-2.3).json             | 3 ++-
 blueprints/Text to Video (Wan 2.2).json             | 5 +++--
 blueprints/Unsharp Mask.json                        | 5 +++--
 blueprints/Video Captioning (Gemini).json           | 3 ++-
 blueprints/Video Inpaint(Wan2.1 VACE).json          | 5 +++--
 blueprints/Video Stitch.json                        | 5 +++--
 blueprints/Video Upscale(GAN x4).json               | 5 +++--
 51 files changed, 153 insertions(+), 95 deletions(-)

diff --git a/blueprints/Brightness and Contrast.json b/blueprints/Brightness and Contrast.json
index 90bfe999d..78fc52f29 100644
--- a/blueprints/Brightness and Contrast.json	
+++ b/blueprints/Brightness and Contrast.json	
@@ -431,9 +431,10 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image Tools/Color adjust"
+        "category": "Image Tools/Color adjust",
+        "description": "Adjusts image brightness and contrast using a real-time GPU fragment shader."
       }
     ]
   },
   "extra": {}
-}
+}
\ No newline at end of file
diff --git a/blueprints/Canny to Image (Z-Image-Turbo).json b/blueprints/Canny to Image (Z-Image-Turbo).json
index ff9717308..14deb64cc 100644
--- a/blueprints/Canny to Image (Z-Image-Turbo).json	
+++ b/blueprints/Canny to Image (Z-Image-Turbo).json	
@@ -162,7 +162,7 @@
         },
         "revision": 0,
         "config": {},
-        "name": "local-Canny to Image (Z-Image-Turbo)",
+        "name": "Canny to Image (Z-Image-Turbo)",
         "inputNode": {
           "id": -10,
           "bounding": [
@@ -1553,7 +1553,8 @@
           "VHS_MetadataImage": true,
           "VHS_KeepIntermediate": true
         },
-        "category": "Image generation and editing/Canny to image"
+        "category": "Image generation and editing/Canny to image",
+        "description": "Generates an image from a Canny edge map using Z-Image-Turbo, with text conditioning."
       }
     ]
   },
@@ -1574,4 +1575,4 @@
     }
   },
   "version": 0.4
-}
+}
\ No newline at end of file
diff --git a/blueprints/Canny to Video (LTX 2.0).json b/blueprints/Canny to Video (LTX 2.0).json
index fae8321b9..a9682c8a4 100644
--- a/blueprints/Canny to Video (LTX 2.0).json	
+++ b/blueprints/Canny to Video (LTX 2.0).json	
@@ -192,7 +192,7 @@
         },
         "revision": 0,
         "config": {},
-        "name": "local-Canny to Video (LTX 2.0)",
+        "name": "Canny to Video (LTX 2.0)",
         "inputNode": {
           "id": -10,
           "bounding": [
@@ -3600,7 +3600,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Video generation and editing/Canny to video"
+        "category": "Video generation and editing/Canny to video",
+        "description": "Generates video from Canny edge maps using LTX-2, with optional synchronized audio."
       }
     ]
   },
@@ -3616,4 +3617,4 @@
     }
   },
   "version": 0.4
-}
+}
\ No newline at end of file
diff --git a/blueprints/Chromatic Aberration.json b/blueprints/Chromatic Aberration.json
index ae8037b1b..893fb1190 100644
--- a/blueprints/Chromatic Aberration.json	
+++ b/blueprints/Chromatic Aberration.json	
@@ -377,8 +377,9 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image Tools/Color adjust"
+        "category": "Image Tools/Color adjust",
+        "description": "Adds lens-style chromatic aberration (color fringing) using a real-time GPU fragment shader."
       }
     ]
   }
-}
+}
\ No newline at end of file
diff --git a/blueprints/Color Adjustment.json b/blueprints/Color Adjustment.json
index 622bf28af..5abbf8baa 100644
--- a/blueprints/Color Adjustment.json	
+++ b/blueprints/Color Adjustment.json	
@@ -596,7 +596,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image Tools/Color adjust"
+        "category": "Image Tools/Color adjust",
+        "description": "Adjusts saturation, temperature, tint, and vibrance using a real-time GPU fragment shader."
       }
     ]
   }
diff --git a/blueprints/Color Balance.json b/blueprints/Color Balance.json
index 21d6319ed..d921eab37 100644
--- a/blueprints/Color Balance.json	
+++ b/blueprints/Color Balance.json	
@@ -1129,7 +1129,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image Tools/Color adjust"
+        "category": "Image Tools/Color adjust",
+        "description": "Balances colors across shadows, midtones, and highlights using a real-time GPU fragment shader."
       }
     ]
   }
diff --git a/blueprints/Color Curves.json b/blueprints/Color Curves.json
index 1461cf396..b9bfb7029 100644
--- a/blueprints/Color Curves.json	
+++ b/blueprints/Color Curves.json	
@@ -608,7 +608,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image Tools/Color adjust"
+        "category": "Image Tools/Color adjust",
+        "description": "Fine-tunes tone and color with per-channel curve adjustments using a real-time GPU fragment shader."
       }
     ]
   }
diff --git a/blueprints/Crop Images 2x2.json b/blueprints/Crop Images 2x2.json
index 2aa42cfc3..99b89b608 100644
--- a/blueprints/Crop Images 2x2.json	
+++ b/blueprints/Crop Images 2x2.json	
@@ -1609,7 +1609,8 @@
           }
         ],
         "extra": {},
-        "category": "Image Tools/Crop"
+        "category": "Image Tools/Crop",
+        "description": "Splits an image into a 2×2 grid of four equal tiles."
       }
     ]
   },
diff --git a/blueprints/Crop Images 3x3.json b/blueprints/Crop Images 3x3.json
index 3a3615ac8..6ac636da4 100644
--- a/blueprints/Crop Images 3x3.json	
+++ b/blueprints/Crop Images 3x3.json	
@@ -2946,7 +2946,8 @@
           }
         ],
         "extra": {},
-        "category": "Image Tools/Crop"
+        "category": "Image Tools/Crop",
+        "description": "Splits an image into a 3×3 grid of nine equal tiles."
       }
     ]
   },
diff --git a/blueprints/Depth to Image (Z-Image-Turbo).json b/blueprints/Depth to Image (Z-Image-Turbo).json
index 4f69a8149..fe9ef0f72 100644
--- a/blueprints/Depth to Image (Z-Image-Turbo).json	
+++ b/blueprints/Depth to Image (Z-Image-Turbo).json	
@@ -1579,7 +1579,8 @@
           "VHS_MetadataImage": true,
           "VHS_KeepIntermediate": true
         },
-        "category": "Image generation and editing/Depth to image"
+        "category": "Image generation and editing/Depth to image",
+        "description": "Generates an image from a depth map using Z-Image-Turbo with text conditioning."
       },
       {
         "id": "458bdf3c-4b58-421c-af50-c9c663a4d74c",
@@ -2461,7 +2462,8 @@
             ]
           },
           "workflowRendererVersion": "LG"
-        }
+        },
+        "description": "Estimates a monocular depth map from an input image using the Lotus depth estimation model."
       }
     ]
   },
diff --git a/blueprints/Depth to Video (ltx 2.0).json b/blueprints/Depth to Video (ltx 2.0).json
index f15212520..bb28695a2 100644
--- a/blueprints/Depth to Video (ltx 2.0).json	
+++ b/blueprints/Depth to Video (ltx 2.0).json	
@@ -4233,7 +4233,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Video generation and editing/Depth to video"
+        "category": "Video generation and editing/Depth to video",
+        "description": "Generates video from depth maps using LTX-2, with optional synchronized audio."
       },
       {
         "id": "38b60539-50a7-42f9-a5fe-bdeca26272e2",
@@ -5192,7 +5193,8 @@
         ],
         "extra": {
           "workflowRendererVersion": "LG"
-        }
+        },
+        "description": "Estimates a monocular depth map from an input image using the Lotus depth estimation model."
       }
     ]
   },
diff --git a/blueprints/Edge-Preserving Blur.json b/blueprints/Edge-Preserving Blur.json
index 18012beb1..fbda9f126 100644
--- a/blueprints/Edge-Preserving Blur.json	
+++ b/blueprints/Edge-Preserving Blur.json	
@@ -450,9 +450,10 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image Tools/Blur"
+        "category": "Image Tools/Blur",
+        "description": "Applies bilateral (edge-preserving) blur to soften images while retaining detail."
       }
     ]
   },
   "extra": {}
-}
+}
\ No newline at end of file
diff --git a/blueprints/Film Grain.json b/blueprints/Film Grain.json
index a680b3ece..3226ea9aa 100644
--- a/blueprints/Film Grain.json	
+++ b/blueprints/Film Grain.json	
@@ -580,8 +580,9 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image Tools/Color adjust"
+        "category": "Image Tools/Color adjust",
+        "description": "Adds procedural film grain texture for a cinematic look via GPU fragment shader."
       }
     ]
   }
-}
+}
\ No newline at end of file
diff --git a/blueprints/First-Last-Frame to Video (LTX-2.3).json b/blueprints/First-Last-Frame to Video (LTX-2.3).json
index 8ec9ed61a..f509aefe0 100644
--- a/blueprints/First-Last-Frame to Video (LTX-2.3).json	
+++ b/blueprints/First-Last-Frame to Video (LTX-2.3).json	
@@ -3350,7 +3350,8 @@
           }
         ],
         "extra": {},
-        "category": "Video generation and editing/First-Last-Frame to Video"
+        "category": "Video generation and editing/First-Last-Frame to Video",
+        "description": "Generates a video interpolating between first and last keyframes using LTX-2.3."
       }
     ]
   },
diff --git a/blueprints/Glow.json b/blueprints/Glow.json
index 1dafb2d35..2bbfdee51 100644
--- a/blueprints/Glow.json
+++ b/blueprints/Glow.json
@@ -575,8 +575,9 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image Tools/Color adjust"
+        "category": "Image Tools/Color adjust",
+        "description": "Adds a glow/bloom effect around bright image areas via GPU fragment shader."
       }
     ]
   }
-}
+}
\ No newline at end of file
diff --git a/blueprints/Hue and Saturation.json b/blueprints/Hue and Saturation.json
index 1a2df8937..cddf0154a 100644
--- a/blueprints/Hue and Saturation.json	
+++ b/blueprints/Hue and Saturation.json	
@@ -752,8 +752,9 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image Tools/Color adjust"
+        "category": "Image Tools/Color adjust",
+        "description": "Adjusts hue, saturation, and lightness of an image using a real-time GPU fragment shader."
       }
     ]
   }
-}
+}
\ No newline at end of file
diff --git a/blueprints/Image Blur.json b/blueprints/Image Blur.json
index 3c7a784b0..0ca8d9931 100644
--- a/blueprints/Image Blur.json	
+++ b/blueprints/Image Blur.json	
@@ -374,7 +374,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image Tools/Blur"
+        "category": "Image Tools/Blur",
+        "description": "Applies Gaussian, Box, or Radial blur to soften images and create stylized depth or motion effects."
       }
     ]
   }
diff --git a/blueprints/Image Captioning (gemini).json b/blueprints/Image Captioning (gemini).json
index 98cfb8999..2fc5d6746 100644
--- a/blueprints/Image Captioning (gemini).json	
+++ b/blueprints/Image Captioning (gemini).json	
@@ -310,7 +310,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Text generation/Image Captioning"
+        "category": "Text generation/Image Captioning",
+        "description": "Generates descriptive captions for images using Google's Gemini multimodal LLM."
       }
     ]
   }
diff --git a/blueprints/Image Channels.json b/blueprints/Image Channels.json
index 9c7b675b2..b6fdff5be 100644
--- a/blueprints/Image Channels.json	
+++ b/blueprints/Image Channels.json	
@@ -315,8 +315,9 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image Tools/Color adjust"
+        "category": "Image Tools/Color adjust",
+        "description": "Manipulates individual RGBA channels for masking, compositing, and channel effects."
       }
     ]
   }
-}
+}
\ No newline at end of file
diff --git a/blueprints/Image Edit (FireRed Image Edit 1.1).json b/blueprints/Image Edit (FireRed Image Edit 1.1).json
index c34246ce6..14310353c 100644
--- a/blueprints/Image Edit (FireRed Image Edit 1.1).json	
+++ b/blueprints/Image Edit (FireRed Image Edit 1.1).json	
@@ -2138,7 +2138,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image generation and editing/Edit image"
+        "category": "Image generation and editing/Edit image",
+        "description": "Edits images via text instructions using FireRed Image Edit 1.1, a diffusion-based instruction-following editing model."
       }
     ]
   },
diff --git a/blueprints/Image Edit (Flux.2 Klein 4B).json b/blueprints/Image Edit (Flux.2 Klein 4B).json
index 6f2f7dc01..7f6fa7a4b 100644
--- a/blueprints/Image Edit (Flux.2 Klein 4B).json	
+++ b/blueprints/Image Edit (Flux.2 Klein 4B).json	
@@ -1472,7 +1472,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image generation and editing/Edit image"
+        "category": "Image generation and editing/Edit image",
+        "description": "Edits an input image via text instructions using FLUX.2 [klein] 4B."
       },
       {
         "id": "6007e698-2ebd-4917-84d8-299b35d7b7ab",
@@ -1821,7 +1822,8 @@
         ],
         "extra": {
           "workflowRendererVersion": "LG"
-        }
+        },
+        "description": "Applies reference image conditioning for style/identity transfer (Flux.2 Klein 4B)."
       }
     ]
   },
@@ -1837,4 +1839,4 @@
     }
   },
   "version": 0.4
-}
\ No newline at end of file
+}
diff --git a/blueprints/Image Edit (LongCat Image Edit).json b/blueprints/Image Edit (LongCat Image Edit).json
index 5b4eb18f0..de1c155a2 100644
--- a/blueprints/Image Edit (LongCat Image Edit).json	
+++ b/blueprints/Image Edit (LongCat Image Edit).json	
@@ -1417,7 +1417,8 @@
           }
         ],
         "extra": {},
-        "category": "Image generation and editing/Edit image"
+        "category": "Image generation and editing/Edit image",
+        "description": "Edits images via text instructions using LongCat Image Edit, an instruction-following image editing diffusion model."
       }
     ]
   },
diff --git a/blueprints/Image Edit (Qwen 2511).json b/blueprints/Image Edit (Qwen 2511).json
index 582171fa0..1aa7e5765 100644
--- a/blueprints/Image Edit (Qwen 2511).json	
+++ b/blueprints/Image Edit (Qwen 2511).json	
@@ -132,7 +132,7 @@
         },
         "revision": 0,
         "config": {},
-        "name": "local-Image Edit (Qwen 2511)",
+        "name": "Image Edit (Qwen 2511)",
         "inputNode": {
           "id": -10,
           "bounding": [
@@ -1468,7 +1468,8 @@
           "VHS_MetadataImage": true,
           "VHS_KeepIntermediate": true
         },
-        "category": "Image generation and editing/Edit image"
+        "category": "Image generation and editing/Edit image",
+        "description": "Edits images via text instructions using Qwen-Image-Edit-2511 with improved character consistency and integrated LoRA."
       }
     ]
   },
@@ -1489,4 +1490,4 @@
     }
   },
   "version": 0.4
-}
+}
\ No newline at end of file
diff --git a/blueprints/Image Inpainting (Flux.1 Fill Dev).json b/blueprints/Image Inpainting (Flux.1 Fill Dev).json
index d40d63594..c1326ed3d 100644
--- a/blueprints/Image Inpainting (Flux.1 Fill Dev).json	
+++ b/blueprints/Image Inpainting (Flux.1 Fill Dev).json	
@@ -1188,7 +1188,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image generation and editing/Inpaint image"
+        "category": "Image generation and editing/Inpaint image",
+        "description": "Inpaints masked image regions using Flux.1 fill [dev], Black Forest Labs' inpainting/outpainting model."
       }
     ]
   },
@@ -1202,4 +1203,4 @@
     },
     "ue_links": []
   }
-}
\ No newline at end of file
+}
diff --git a/blueprints/Image Inpainting (Qwen-image).json b/blueprints/Image Inpainting (Qwen-image).json
index 95b2909fa..a06d57e19 100644
--- a/blueprints/Image Inpainting (Qwen-image).json	
+++ b/blueprints/Image Inpainting (Qwen-image).json	
@@ -1548,7 +1548,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image generation and editing/Inpaint image"
+        "category": "Image generation and editing/Inpaint image",
+        "description": "Inpaints masked regions using Qwen-Image, extending its multilingual text rendering to inpainting tasks."
       },
       {
         "id": "56a1f603-fbd2-40ed-94ef-c9ecbd96aca8",
@@ -1907,7 +1908,8 @@
         ],
         "extra": {
           "workflowRendererVersion": "LG"
-        }
+        },
+        "description": "Expands and softens mask edges to reduce visible seams after image processing."
       }
     ]
   },
diff --git a/blueprints/Image Levels.json b/blueprints/Image Levels.json
index ef256a1aa..1a1b18932 100644
--- a/blueprints/Image Levels.json	
+++ b/blueprints/Image Levels.json	
@@ -742,9 +742,10 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image Tools/Color adjust"
+        "category": "Image Tools/Color adjust",
+        "description": "Adjusts black point, white point, and gamma for tonal range control via GPU shader."
       }
     ]
   },
   "extra": {}
-}
+}
\ No newline at end of file
diff --git a/blueprints/Image Outpainting (Qwen-Image).json b/blueprints/Image Outpainting (Qwen-Image).json
index 218fdc775..6c07227c0 100644
--- a/blueprints/Image Outpainting (Qwen-Image).json	
+++ b/blueprints/Image Outpainting (Qwen-Image).json	
@@ -1919,7 +1919,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image generation and editing/Outpaint image"
+        "category": "Image generation and editing/Outpaint image",
+        "description": "Outpaints beyond image boundaries using Qwen-Image's outpainting capabilities."
       },
       {
         "id": "f93c215e-c393-460e-9534-ed2c3d8a652e",
@@ -2278,7 +2279,8 @@
         ],
         "extra": {
           "workflowRendererVersion": "LG"
-        }
+        },
+        "description": "Expands and softens mask edges to reduce visible seams after image processing."
       },
       {
         "id": "2a4b2cc0-db37-4302-a067-da392f38f06b",
@@ -2733,7 +2735,8 @@
         ],
         "extra": {
           "workflowRendererVersion": "LG"
-        }
+        },
+        "description": "Scales both image and mask together while preserving alignment for editing workflows."
       }
     ]
   },
diff --git a/blueprints/Image Upscale(Z-image-Turbo).json b/blueprints/Image Upscale(Z-image-Turbo).json
index 0d2b6e240..bd803a0b1 100644
--- a/blueprints/Image Upscale(Z-image-Turbo).json	
+++ b/blueprints/Image Upscale(Z-image-Turbo).json	
@@ -141,7 +141,7 @@
         },
         "revision": 0,
         "config": {},
-        "name": "local-Image Upscale(Z-image-Turbo)",
+        "name": "Image Upscale (Z-image-Turbo)",
         "inputNode": {
           "id": -10,
           "bounding": [
@@ -1302,7 +1302,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image generation and editing/Enhance"
+        "category": "Image generation and editing/Enhance",
+        "description": "Upscales images to higher resolution using Z-Image-Turbo."
       }
     ]
   },
diff --git a/blueprints/Image to Depth Map (Lotus).json b/blueprints/Image to Depth Map (Lotus).json
index 089f2cd42..12f10ba5b 100644
--- a/blueprints/Image to Depth Map (Lotus).json	
+++ b/blueprints/Image to Depth Map (Lotus).json	
@@ -99,7 +99,7 @@
         },
         "revision": 0,
         "config": {},
-        "name": "local-Image to Depth Map (Lotus)",
+        "name": "Image to Depth Map (Lotus)",
         "inputNode": {
           "id": -10,
           "bounding": [
@@ -948,7 +948,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image generation and editing/Depth to image"
+        "category": "Image generation and editing/Depth to image",
+        "description": "Estimates a monocular depth map from an input image using the Lotus depth estimation model."
       }
     ]
   },
@@ -964,4 +965,4 @@
     "workflowRendererVersion": "LG"
   },
   "version": 0.4
-}
+}
\ No newline at end of file
diff --git a/blueprints/Image to Layers(Qwen-Image-Layered).json b/blueprints/Image to Layers(Qwen-Image-Layered).json
index 8a525e7a5..7b44f0563 100644
--- a/blueprints/Image to Layers(Qwen-Image-Layered).json	
+++ b/blueprints/Image to Layers(Qwen-Image-Layered).json	
@@ -1586,7 +1586,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image generation and editing/Image to layers"
+        "category": "Image generation and editing/Image to layers",
+        "description": "Decomposes an image into variable-resolution RGBA layers for independent editing using Qwen-Image-Layered."
       }
     ]
   },
diff --git a/blueprints/Image to Model (Hunyuan3d 2.1).json b/blueprints/Image to Model (Hunyuan3d 2.1).json
index 4705603a8..ee5552656 100644
--- a/blueprints/Image to Model (Hunyuan3d 2.1).json	
+++ b/blueprints/Image to Model (Hunyuan3d 2.1).json	
@@ -72,7 +72,7 @@
         },
         "revision": 0,
         "config": {},
-        "name": "local-Image to Model (Hunyuan3d 2.1)",
+        "name": "Image to 3D Model (Hunyuan3d 2.1)",
         "inputNode": {
           "id": -10,
           "bounding": [
@@ -765,7 +765,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "3D/Image to 3D Model"
+        "category": "3D/Image to 3D Model",
+        "description": "Generates 3D mesh models from a single input image using Hunyuan3D 2.0/2.1."
       }
     ]
   },
diff --git a/blueprints/Image to Video (LTX-2.3).json b/blueprints/Image to Video (LTX-2.3).json
index 86a601130..3db524ea0 100644
--- a/blueprints/Image to Video (LTX-2.3).json	
+++ b/blueprints/Image to Video (LTX-2.3).json	
@@ -4223,7 +4223,8 @@
         "extra": {
           "workflowRendererVersion": "Vue-corrected"
         },
-        "category": "Video generation and editing/Image to video"
+        "category": "Video generation and editing/Image to video",
+        "description": "Generates video from a single input image using LTX-2.3."
       }
     ]
   },
diff --git a/blueprints/Image to Video (Wan 2.2).json b/blueprints/Image to Video (Wan 2.2).json
index a8dafd3c9..3510aad18 100644
--- a/blueprints/Image to Video (Wan 2.2).json	
+++ b/blueprints/Image to Video (Wan 2.2).json	
@@ -206,7 +206,7 @@
         },
         "revision": 0,
         "config": {},
-        "name": "local-Image to Video (Wan 2.2)",
+        "name": "Image to Video (Wan 2.2)",
         "inputNode": {
           "id": -10,
           "bounding": [
@@ -2027,7 +2027,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Video generation and editing/Image to video"
+        "category": "Video generation and editing/Image to video",
+        "description": "Generates video from an image and text prompt using Wan 2.2, supporting T2V and I2V."
       }
     ]
   },
diff --git a/blueprints/Pose to Image (Z-Image-Turbo).json b/blueprints/Pose to Image (Z-Image-Turbo).json
index a55410ba4..5c2749efe 100644
--- a/blueprints/Pose to Image (Z-Image-Turbo).json	
+++ b/blueprints/Pose to Image (Z-Image-Turbo).json	
@@ -134,7 +134,7 @@
         },
         "revision": 0,
         "config": {},
-        "name": "local-Pose to Image (Z-Image-Turbo)",
+        "name": "Pose to Image (Z-Image-Turbo)",
         "inputNode": {
           "id": -10,
           "bounding": [
@@ -1298,7 +1298,8 @@
           "VHS_MetadataImage": true,
           "VHS_KeepIntermediate": true
         },
-        "category": "Image generation and editing/Pose to image"
+        "category": "Image generation and editing/Pose to image",
+        "description": "Generates an image from pose keypoints using Z-Image-Turbo with text conditioning."
       }
     ]
   },
@@ -1319,4 +1320,4 @@
     }
   },
   "version": 0.4
-}
+}
\ No newline at end of file
diff --git a/blueprints/Pose to Video (LTX 2.0).json b/blueprints/Pose to Video (LTX 2.0).json
index 580900bc0..1ce49351a 100644
--- a/blueprints/Pose to Video (LTX 2.0).json	
+++ b/blueprints/Pose to Video (LTX 2.0).json	
@@ -3870,7 +3870,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Video generation and editing/Pose to video"
+        "category": "Video generation and editing/Pose to video",
+        "description": "Generates video from pose reference frames using LTX-2, with optional synchronized audio."
       }
     ]
   },
diff --git a/blueprints/Prompt Enhance.json b/blueprints/Prompt Enhance.json
index 5e57548ff..e260b1203 100644
--- a/blueprints/Prompt Enhance.json	
+++ b/blueprints/Prompt Enhance.json	
@@ -270,9 +270,10 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Text generation/Prompt enhance"
+        "category": "Text generation/Prompt enhance",
+        "description": "Expands short text prompts into detailed descriptions using a text generation model for better generation quality."
       }
     ]
   },
   "extra": {}
-}
+}
\ No newline at end of file
diff --git a/blueprints/Sharpen.json b/blueprints/Sharpen.json
index f332400fd..3c4099c6b 100644
--- a/blueprints/Sharpen.json
+++ b/blueprints/Sharpen.json
@@ -302,8 +302,9 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image Tools/Sharpen"
+        "category": "Image Tools/Sharpen",
+        "description": "Sharpens image details using a GPU fragment shader for enhanced clarity."
       }
     ]
   }
-}
+}
\ No newline at end of file
diff --git a/blueprints/Text to Audio (ACE-Step 1.5).json b/blueprints/Text to Audio (ACE-Step 1.5).json
index 206cf16be..5b8b8626f 100644
--- a/blueprints/Text to Audio (ACE-Step 1.5).json	
+++ b/blueprints/Text to Audio (ACE-Step 1.5).json	
@@ -222,7 +222,7 @@
         },
         "revision": 0,
         "config": {},
-        "name": "local-Text to Audio (ACE-Step 1.5)",
+        "name": "Text to Audio (ACE-Step 1.5)",
         "inputNode": {
           "id": -10,
           "bounding": [
@@ -1502,7 +1502,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Audio/Music generation"
+        "category": "Audio/Music generation",
+        "description": "Generates audio/music from text prompts using ACE-Step 1.5, a diffusion-based audio generation model."
       }
     ]
   },
@@ -1518,4 +1519,4 @@
     }
   },
   "version": 0.4
-}
+}
\ No newline at end of file
diff --git a/blueprints/Text to Image (Flux.1 Dev).json b/blueprints/Text to Image (Flux.1 Dev).json
index 04c3cb95a..45f68f508 100644
--- a/blueprints/Text to Image (Flux.1 Dev).json	
+++ b/blueprints/Text to Image (Flux.1 Dev).json	
@@ -1029,7 +1029,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image generation and editing/Text to image"
+        "category": "Image generation and editing/Text to image",
+        "description": "Generates images from text prompts using Flux.1 [dev], Black Forest Labs' 12B diffusion model."
       }
     ]
   },
@@ -1043,4 +1044,4 @@
     },
     "ue_links": []
   }
-}
\ No newline at end of file
+}
diff --git a/blueprints/Text to Image (Flux.1 Krea Dev).json b/blueprints/Text to Image (Flux.1 Krea Dev).json
index fe4db1cfc..30a78dca1 100644
--- a/blueprints/Text to Image (Flux.1 Krea Dev).json	
+++ b/blueprints/Text to Image (Flux.1 Krea Dev).json	
@@ -1023,7 +1023,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image generation and editing/Text to image"
+        "category": "Image generation and editing/Text to image",
+        "description": "Generates images from text prompts using Flux.1 Krea Dev, a Black Forest Labs × Krea collaboration variant."
       }
     ]
   },
@@ -1037,4 +1038,4 @@
     },
     "ue_links": []
   }
-}
\ No newline at end of file
+}
diff --git a/blueprints/Text to Image (NetaYume Lumina).json b/blueprints/Text to Image (NetaYume Lumina).json
index 394ad1608..9e11b7a86 100644
--- a/blueprints/Text to Image (NetaYume Lumina).json	
+++ b/blueprints/Text to Image (NetaYume Lumina).json	
@@ -1104,7 +1104,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image generation and editing/Text to image"
+        "category": "Image generation and editing/Text to image",
+        "description": "Generates images from text prompts using NetaYume Lumina, fine-tuned from Neta Lumina for anime-style and illustration generation."
       },
       {
         "id": "a07fdf06-1bda-4dac-bdbd-63ee8ebca1c9",
@@ -1458,11 +1459,12 @@
         ],
         "extra": {
           "workflowRendererVersion": "LG"
-        }
+        },
+        "description": "Encodes a negative text prompt via CLIP for classifier-free guidance in anime-style generation (NetaYume Lumina)."
       }
     ]
   },
   "extra": {
     "ue_links": []
   }
-}
\ No newline at end of file
+}
diff --git a/blueprints/Text to Image (Qwen-Image 2512).json b/blueprints/Text to Image (Qwen-Image 2512).json
index f52ea2ef2..09612be8b 100644
--- a/blueprints/Text to Image (Qwen-Image 2512).json	
+++ b/blueprints/Text to Image (Qwen-Image 2512).json	
@@ -1941,7 +1941,8 @@
         "extra": {
           "workflowRendererVersion": "Vue-corrected"
         },
-        "category": "Image generation and editing/Text to image"
+        "category": "Image generation and editing/Text to image",
+        "description": "Generates images from text prompts using Qwen-Image-2512, with enhanced human realism and finer natural detail over the base version."
       }
     ]
   },
diff --git a/blueprints/Text to Image (Qwen-Image).json b/blueprints/Text to Image (Qwen-Image).json
index 70b4b44b3..e78d5a962 100644
--- a/blueprints/Text to Image (Qwen-Image).json	
+++ b/blueprints/Text to Image (Qwen-Image).json	
@@ -1873,7 +1873,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image generation and editing/Text to image"
+        "category": "Image generation and editing/Text to image",
+        "description": "Generates images from text prompts using Qwen-Image, Alibaba's 20B MMDiT model with excellent multilingual text rendering."
       }
     ]
   },
diff --git a/blueprints/Text to Image (Z-Image-Turbo).json b/blueprints/Text to Image (Z-Image-Turbo).json
index 6aa80e327..6975151ea 100644
--- a/blueprints/Text to Image (Z-Image-Turbo).json	
+++ b/blueprints/Text to Image (Z-Image-Turbo).json	
@@ -149,7 +149,7 @@
         },
         "revision": 0,
         "config": {},
-        "name": "local-Text to Image (Z-Image-Turbo)",
+        "name": "Text to Image (Z-Image-Turbo)",
         "inputNode": {
           "id": -10,
           "bounding": [
@@ -1054,7 +1054,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image generation and editing/Text to image"
+        "category": "Image generation and editing/Text to image",
+        "description": "Generates images from text prompts using Z-Image-Turbo, Alibaba's distilled 6B DiT model."
       }
     ]
   },
@@ -1075,4 +1076,4 @@
     }
   },
   "version": 0.4
-}
+}
\ No newline at end of file
diff --git a/blueprints/Text to Video (LTX-2.3).json b/blueprints/Text to Video (LTX-2.3).json
index ff9bc6ccf..f44a216dd 100644
--- a/blueprints/Text to Video (LTX-2.3).json	
+++ b/blueprints/Text to Video (LTX-2.3).json	
@@ -4286,7 +4286,8 @@
         "extra": {
           "workflowRendererVersion": "Vue-corrected"
         },
-        "category": "Video generation and editing/Text to video"
+        "category": "Video generation and editing/Text to video",
+        "description": "Generates video from text prompts using LTX-2.3, Lightricks' video diffusion model."
       }
     ]
   },
diff --git a/blueprints/Text to Video (Wan 2.2).json b/blueprints/Text to Video (Wan 2.2).json
index 0ce485b67..a264a490d 100644
--- a/blueprints/Text to Video (Wan 2.2).json	
+++ b/blueprints/Text to Video (Wan 2.2).json	
@@ -1572,7 +1572,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Video generation and editing/Text to video"
+        "category": "Video generation and editing/Text to video",
+        "description": "Generates video from text prompts using Wan2.2, Alibaba's diffusion video model."
       }
     ]
   },
@@ -1586,4 +1587,4 @@
     "VHS_KeepIntermediate": true
   },
   "version": 0.4
-}
+}
\ No newline at end of file
diff --git a/blueprints/Unsharp Mask.json b/blueprints/Unsharp Mask.json
index 137acaa43..79a4c954f 100644
--- a/blueprints/Unsharp Mask.json	
+++ b/blueprints/Unsharp Mask.json	
@@ -434,8 +434,9 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Image Tools/Sharpen"
+        "category": "Image Tools/Sharpen",
+        "description": "Enhances edge contrast via unsharp masking for a sharper image appearance."
       }
     ]
   }
-}
+}
\ No newline at end of file
diff --git a/blueprints/Video Captioning (Gemini).json b/blueprints/Video Captioning (Gemini).json
index ea6dc8bee..7642b23c1 100644
--- a/blueprints/Video Captioning (Gemini).json	
+++ b/blueprints/Video Captioning (Gemini).json	
@@ -307,7 +307,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Text generation/Video Captioning"
+        "category": "Text generation/Video Captioning",
+        "description": "Generates descriptive captions for video input using Google's Gemini multimodal LLM."
       }
     ]
   }
diff --git a/blueprints/Video Inpaint(Wan2.1 VACE).json b/blueprints/Video Inpaint(Wan2.1 VACE).json
index f404e6773..a658be5f8 100644
--- a/blueprints/Video Inpaint(Wan2.1 VACE).json	
+++ b/blueprints/Video Inpaint(Wan2.1 VACE).json	
@@ -165,7 +165,7 @@
         },
         "revision": 0,
         "config": {},
-        "name": "local-Video Inpaint(Wan2.1 VACE)",
+        "name": "Video Inpaint (Wan 2.1 VACE)",
         "inputNode": {
           "id": -10,
           "bounding": [
@@ -2368,7 +2368,8 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Video generation and editing/Inpaint video"
+        "category": "Video generation and editing/Inpaint video",
+        "description": "Inpaints masked regions in video frames using Wan 2.1 VACE."
       }
     ]
   },
diff --git a/blueprints/Video Stitch.json b/blueprints/Video Stitch.json
index 020896d78..6eb0f0bbf 100644
--- a/blueprints/Video Stitch.json	
+++ b/blueprints/Video Stitch.json	
@@ -584,8 +584,9 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Video Tools/Stitch videos"
+        "category": "Video Tools/Stitch videos",
+        "description": "Stitches multiple video clips into a single sequential video file."
       }
     ]
   }
-}
+}
\ No newline at end of file
diff --git a/blueprints/Video Upscale(GAN x4).json b/blueprints/Video Upscale(GAN x4).json
index b61dc88d7..73476e36b 100644
--- a/blueprints/Video Upscale(GAN x4).json	
+++ b/blueprints/Video Upscale(GAN x4).json	
@@ -412,9 +412,10 @@
         "extra": {
           "workflowRendererVersion": "LG"
         },
-        "category": "Video generation and editing/Enhance video"
+        "category": "Video generation and editing/Enhance video",
+        "description": "Upscales video to 4× resolution using a GAN-based upscaling model."
       }
     ]
   },
   "extra": {}
-}
+}
\ No newline at end of file

From 7bbf1e8169fa3080841b83914fa9901793b66b71 Mon Sep 17 00:00:00 2001
From: Alexander Piskun <13381981+bigcat88@users.noreply.github.com>
Date: Sat, 9 May 2026 07:38:17 +0300
Subject: [PATCH 10/10] [Partner Nodes] Tripo3D 3.1 model (#13788)

* feat(api-nodes): add Tripo3D 3.1 model

Signed-off-by: bigcat88 <bigcat88@icloud.com>

* fix: price badges algo

Signed-off-by: bigcat88 <bigcat88@icloud.com>

* [Partner Nodes] deprecate "quad" param for the TripoMultiviewToModel node

Signed-off-by: bigcat88 <bigcat88@icloud.com>

---------

Signed-off-by: bigcat88 <bigcat88@icloud.com>
---
 comfy_api_nodes/apis/tripo.py  | 30 ++++--------
 comfy_api_nodes/nodes_tripo.py | 84 +++++++++++-----------------------
 2 files changed, 36 insertions(+), 78 deletions(-)

diff --git a/comfy_api_nodes/apis/tripo.py b/comfy_api_nodes/apis/tripo.py
index ffaaa7dc1..bce6b0e89 100644
--- a/comfy_api_nodes/apis/tripo.py
+++ b/comfy_api_nodes/apis/tripo.py
@@ -1,10 +1,11 @@
-from __future__ import annotations
 from enum import Enum
-from typing import Optional, List, Dict, Any, Union
+from typing import Optional, Any
 
 from pydantic import BaseModel, Field, RootModel
 
+
 class TripoModelVersion(str, Enum):
+    v3_1_20260211 = 'v3.1-20260211'
     v3_0_20250812 = 'v3.0-20250812'
     v2_5_20250123 = 'v2.5-20250123'
     v2_0_20240919 = 'v2.0-20240919'
@@ -142,7 +143,7 @@ class TripoFileEmptyReference(BaseModel):
     pass
 
 class TripoFileReference(RootModel):
-    root: Union[TripoFileTokenReference, TripoUrlReference, TripoObjectReference, TripoFileEmptyReference]
+    root: TripoFileTokenReference | TripoUrlReference | TripoObjectReference | TripoFileEmptyReference
 
 class TripoGetStsTokenRequest(BaseModel):
     format: str = Field(..., description='The format of the image')
@@ -183,7 +184,7 @@ class TripoImageToModelRequest(BaseModel):
 
 class TripoMultiviewToModelRequest(BaseModel):
     type: TripoTaskType = TripoTaskType.MULTIVIEW_TO_MODEL
-    files: List[TripoFileReference] = Field(..., description='The file references to convert to a model')
+    files: list[TripoFileReference] = Field(..., description='The file references to convert to a model')
     model_version: Optional[TripoModelVersion] = Field(None, description='The model version to use for generation')
     orthographic_projection: Optional[bool] = Field(False, description='Whether to use orthographic projection')
     face_limit: Optional[int] = Field(None, description='The number of faces to limit the generation to')
@@ -251,27 +252,13 @@ class TripoConvertModelRequest(BaseModel):
     with_animation: Optional[bool] = Field(None, description='Whether to include animations')
     pack_uv: Optional[bool] = Field(None, description='Whether to pack the UVs')
     bake: Optional[bool] = Field(None, description='Whether to bake the model')
-    part_names: Optional[List[str]] = Field(None, description='The names of the parts to include')
+    part_names: Optional[list[str]] = Field(None, description='The names of the parts to include')
     fbx_preset: Optional[TripoFbxPreset] = Field(None, description='The preset for the FBX export')
     export_vertex_colors: Optional[bool] = Field(None, description='Whether to export the vertex colors')
     export_orientation: Optional[TripoOrientation] = Field(None, description='The orientation for the export')
     animate_in_place: Optional[bool] = Field(None, description='Whether to animate in place')
 
 
-class TripoTaskRequest(RootModel):
-    root: Union[
-        TripoTextToModelRequest,
-        TripoImageToModelRequest,
-        TripoMultiviewToModelRequest,
-        TripoTextureModelRequest,
-        TripoRefineModelRequest,
-        TripoAnimatePrerigcheckRequest,
-        TripoAnimateRigRequest,
-        TripoAnimateRetargetRequest,
-        TripoStylizeModelRequest,
-        TripoConvertModelRequest
-    ]
-
 class TripoTaskOutput(BaseModel):
     model: Optional[str] = Field(None, description='URL to the model')
     base_model: Optional[str] = Field(None, description='URL to the base model')
@@ -283,12 +270,13 @@ class TripoTask(BaseModel):
     task_id: str = Field(..., description='The task ID')
     type: Optional[str] = Field(None, description='The type of task')
     status: Optional[TripoTaskStatus] = Field(None, description='The status of the task')
-    input: Optional[Dict[str, Any]] = Field(None, description='The input parameters for the task')
+    input: Optional[dict[str, Any]] = Field(None, description='The input parameters for the task')
     output: Optional[TripoTaskOutput] = Field(None, description='The output of the task')
     progress: Optional[int] = Field(None, description='The progress of the task', ge=0, le=100)
     create_time: Optional[int] = Field(None, description='The creation time of the task')
     running_left_time: Optional[int] = Field(None, description='The estimated time left for the task')
     queue_position: Optional[int] = Field(None, description='The position in the queue')
+    consumed_credit: int | None = Field(None)
 
 class TripoTaskResponse(BaseModel):
     code: int = Field(0, description='The response code')
@@ -296,7 +284,7 @@ class TripoTaskResponse(BaseModel):
 
 class TripoGeneralResponse(BaseModel):
     code: int = Field(0, description='The response code')
-    data: Dict[str, str] = Field(..., description='The task ID data')
+    data: dict[str, str] = Field(..., description='The task ID data')
 
 class TripoBalanceData(BaseModel):
     balance: float = Field(..., description='The account balance')
diff --git a/comfy_api_nodes/nodes_tripo.py b/comfy_api_nodes/nodes_tripo.py
index 9f4298dce..d6501dee4 100644
--- a/comfy_api_nodes/nodes_tripo.py
+++ b/comfy_api_nodes/nodes_tripo.py
@@ -60,6 +60,7 @@ async def poll_until_finished(
         ],
         status_extractor=lambda x: x.data.status,
         progress_extractor=lambda x: x.data.progress,
+        price_extractor=lambda x: x.data.consumed_credit * 0.01 if x.data.consumed_credit else None,
         estimated_duration=average_duration,
     )
     if response_poll.data.status == TripoTaskStatus.SUCCESS:
@@ -113,7 +114,6 @@ class TripoTextToModelNode(IO.ComfyNode):
                 depends_on=IO.PriceBadgeDepends(
                     widgets=[
                         "model_version",
-                        "style",
                         "texture",
                         "pbr",
                         "quad",
@@ -124,20 +124,17 @@ class TripoTextToModelNode(IO.ComfyNode):
                 expr="""
                 (
                   $isV14 := $contains(widgets.model_version,"v1.4");
-                  $style := widgets.style;
-                  $hasStyle := ($style != "" and $style != "none");
+                  $isV3OrLater := $contains(widgets.model_version,"v3.");
                   $withTexture := widgets.texture or widgets.pbr;
                   $isHdTexture := (widgets.texture_quality = "detailed");
                   $isDetailedGeometry := (widgets.geometry_quality = "detailed");
-                  $baseCredits :=
-                    $isV14 ? 20 : ($withTexture ? 20 : 10);
-                  $credits :=
-                    $baseCredits
-                    + ($hasStyle ? 5 : 0)
+                  $credits := $isV14 ? 20 : (
+                    ($withTexture ? 20 : 10)
                     + (widgets.quad ? 5 : 0)
                     + ($isHdTexture ? 10 : 0)
-                    + ($isDetailedGeometry ? 20 : 0);
-                  {"type":"usd","usd": $round($credits * 0.01, 2)}
+                    + (($isDetailedGeometry and $isV3OrLater) ? 20 : 0)
+                  );
+                  {"type":"usd","usd": $round($credits * 0.01, 2), "format": {"approximate": true}}
                 )
                 """,
             ),
@@ -239,7 +236,6 @@ class TripoImageToModelNode(IO.ComfyNode):
                 depends_on=IO.PriceBadgeDepends(
                     widgets=[
                         "model_version",
-                        "style",
                         "texture",
                         "pbr",
                         "quad",
@@ -250,20 +246,17 @@ class TripoImageToModelNode(IO.ComfyNode):
                 expr="""
                 (
                   $isV14 := $contains(widgets.model_version,"v1.4");
-                  $style := widgets.style;
-                  $hasStyle := ($style != "" and $style != "none");
+                  $isV3OrLater := $contains(widgets.model_version,"v3.");
                   $withTexture := widgets.texture or widgets.pbr;
                   $isHdTexture := (widgets.texture_quality = "detailed");
                   $isDetailedGeometry := (widgets.geometry_quality = "detailed");
-                  $baseCredits :=
-                    $isV14 ? 30 : ($withTexture ? 30 : 20);
-                  $credits :=
-                    $baseCredits
-                    + ($hasStyle ? 5 : 0)
+                  $credits := $isV14 ? 30 : (
+                    ($withTexture ? 30 : 20)
                     + (widgets.quad ? 5 : 0)
                     + ($isHdTexture ? 10 : 0)
-                    + ($isDetailedGeometry ? 20 : 0);
-                  {"type":"usd","usd": $round($credits * 0.01, 2)}
+                    + (($isDetailedGeometry and $isV3OrLater) ? 20 : 0)
+                  );
+                  {"type":"usd","usd": $round($credits * 0.01, 2), "format": {"approximate": true}}
                 )
                 """,
             ),
@@ -358,7 +351,7 @@ class TripoMultiviewToModelNode(IO.ComfyNode):
                     "texture_alignment", default="original_image", options=["original_image", "geometry"], optional=True, advanced=True
                 ),
                 IO.Int.Input("face_limit", default=-1, min=-1, max=500000, optional=True, advanced=True),
-                IO.Boolean.Input("quad", default=False, optional=True, advanced=True),
+                IO.Boolean.Input("quad", default=False, optional=True, advanced=True, tooltip="This parameter is deprecated and does nothing."),
                 IO.Combo.Input("geometry_quality", default="standard", options=["standard", "detailed"], optional=True, advanced=True),
             ],
             outputs=[
@@ -379,7 +372,6 @@ class TripoMultiviewToModelNode(IO.ComfyNode):
                         "model_version",
                         "texture",
                         "pbr",
-                        "quad",
                         "texture_quality",
                         "geometry_quality",
                     ],
@@ -387,17 +379,16 @@ class TripoMultiviewToModelNode(IO.ComfyNode):
                 expr="""
                 (
                   $isV14 := $contains(widgets.model_version,"v1.4");
+                  $isV3OrLater := $contains(widgets.model_version,"v3.");
                   $withTexture := widgets.texture or widgets.pbr;
                   $isHdTexture := (widgets.texture_quality = "detailed");
                   $isDetailedGeometry := (widgets.geometry_quality = "detailed");
-                  $baseCredits :=
-                    $isV14 ? 30 : ($withTexture ? 30 : 20);
-                  $credits :=
-                    $baseCredits
-                    + (widgets.quad ? 5 : 0)
+                  $credits := $isV14 ? 30 : (
+                    ($withTexture ? 30 : 20)
                     + ($isHdTexture ? 10 : 0)
-                    + ($isDetailedGeometry ? 20 : 0);
-                  {"type":"usd","usd": $round($credits * 0.01, 2)}
+                    + (($isDetailedGeometry and $isV3OrLater) ? 20 : 0)
+                  );
+                  {"type":"usd","usd": $round($credits * 0.01, 2), "format": {"approximate": true}}
                 )
                 """,
             ),
@@ -457,7 +448,7 @@ class TripoMultiviewToModelNode(IO.ComfyNode):
                 geometry_quality=geometry_quality,
                 texture_alignment=texture_alignment,
                 face_limit=face_limit if face_limit != -1 else None,
-                quad=quad,
+                quad=None,
             ),
         )
         return await poll_until_finished(cls, response, average_duration=80)
@@ -498,7 +489,7 @@ class TripoTextureNode(IO.ComfyNode):
                 expr="""
                 (
                   $tq := widgets.texture_quality;
-                  {"type":"usd","usd": ($contains($tq,"detailed") ? 0.2 : 0.1)}
+                  {"type":"usd","usd": ($contains($tq,"detailed") ? 0.2 : 0.1), "format": {"approximate": true}}
                 )
                 """,
             ),
@@ -555,7 +546,7 @@ class TripoRefineNode(IO.ComfyNode):
             is_api_node=True,
             is_output_node=True,
             price_badge=IO.PriceBadge(
-                expr="""{"type":"usd","usd":0.3}""",
+                expr="""{"type":"usd","usd":0.3, "format": {"approximate": true}}""",
             ),
         )
 
@@ -592,7 +583,7 @@ class TripoRigNode(IO.ComfyNode):
             is_api_node=True,
             is_output_node=True,
             price_badge=IO.PriceBadge(
-                expr="""{"type":"usd","usd":0.25}""",
+                expr="""{"type":"usd","usd":0.25, "format": {"approximate": true}}""",
             ),
         )
 
@@ -652,7 +643,7 @@ class TripoRetargetNode(IO.ComfyNode):
             is_api_node=True,
             is_output_node=True,
             price_badge=IO.PriceBadge(
-                expr="""{"type":"usd","usd":0.1}""",
+                expr="""{"type":"usd","usd":0.1, "format": {"approximate": true}}""",
             ),
         )
 
@@ -761,19 +752,10 @@ class TripoConversionNode(IO.ComfyNode):
                         "face_limit",
                         "texture_size",
                         "texture_format",
-                        "force_symmetry",
                         "flatten_bottom",
                         "flatten_bottom_threshold",
                         "pivot_to_center_bottom",
                         "scale_factor",
-                        "with_animation",
-                        "pack_uv",
-                        "bake",
-                        "part_names",
-                        "fbx_preset",
-                        "export_vertex_colors",
-                        "export_orientation",
-                        "animate_in_place",
                     ],
                 ),
                 expr="""
@@ -783,28 +765,16 @@ class TripoConversionNode(IO.ComfyNode):
                     $flatThresh := (widgets.flatten_bottom_threshold != null) ? widgets.flatten_bottom_threshold : 0;
                     $scale := (widgets.scale_factor != null) ? widgets.scale_factor : 1;
                     $texFmt := (widgets.texture_format != "" ? widgets.texture_format : "jpeg");
-                    $part := widgets.part_names;
-                    $fbx := (widgets.fbx_preset != "" ? widgets.fbx_preset : "blender");
-                    $orient := (widgets.export_orientation != "" ? widgets.export_orientation : "default");
                     $advanced :=
                       widgets.quad or
-                      widgets.force_symmetry or
                       widgets.flatten_bottom or
                       widgets.pivot_to_center_bottom or
-                      widgets.with_animation or
-                      widgets.pack_uv or
-                      widgets.bake or
-                      widgets.export_vertex_colors or
-                      widgets.animate_in_place or
                       ($face != -1) or
                       ($texSize != 4096) or
                       ($flatThresh != 0) or
                       ($scale != 1) or
-                      ($texFmt != "jpeg") or
-                      ($part != "") or
-                      ($fbx != "blender") or
-                      ($orient != "default");
-                    {"type":"usd","usd": ($advanced ? 0.1 : 0.05)}
+                      ($texFmt != "jpeg");
+                    {"type":"usd","usd": ($advanced ? 0.1 : 0.05), "format": {"approximate": true}}
                 )
                 """,
             ),