ComfyUI-OpenClaw/docs/asset_api_adoption_decision.md

ComfyUI Asset API Adoption Decision (2026-04-16)

2026-07-08 reference anchor update

• Current reference anchor is ComfyUI 51bf508a (v0.27.0-25-g51bf508a, pyproject 0.27.0).
• SaveImage output sockets, 3D preview refs, typed asset dimensions, grouped asset downloads, and hash / asset_hash aliases do not change the no-go decision.
• OpenClaw continues to use /history + /view; asset-service-only refs stay explicit asset_api_required states.

2026-06-12 reconfirmation

• Current output parsing is media-aware for ComfyUI result groups images, video, audio, 3d, and bounded text.
• File-like media refs still use /view when they provide filename or hash-backed preview metadata.
• Text output previews are bounded and rendered as text, not HTML.
• Asset-service-only identifiers remain explicit fallback states and still do not trigger automatic direct /api/assets fetches.

2026-05-31 reconfirmation

• Current host reference evidence shows upstream asset responses may expose hash alongside asset_hash.
• OpenClaw accepts hash as an alias for hash-backed previews, but still resolves those refs through /view?filename=blake3:....
• This does not change the no-go decision for automatic direct /api/assets runtime fetches.

Scope

• Goal: decide whether OpenClaw should adopt upstream /api/assets semantics as a normal runtime dependency beyond the bounded /view interoperability layer.

Current baseline

• Current history/output-facing interop already accepts:
  • classic ComfyUI output refs (filename, subfolder, type)
  • asset-hash-backed refs that still resolve through /view?filename=blake3:...
  • media-aware output groups (images, video, audio, 3d, and bounded text)
• Current ComfyUI 51bf508a / v0.27.0-25-g51bf508a / pyproject 0.27.0 reference facts:
  • /api/assets* routes exist, but operational use is feature-gated behind --enable-assets
  • /features exposes the assets capability flag so hosts can report whether the asset system is enabled
  • frontend preview still resolves blake3:... asset hashes through /view, so hash-backed outputs do not require a direct /api/assets fetch
  • asset responses may expose hash alongside asset_hash; OpenClaw treats both as hash-backed preview aliases
• Current operator/runtime surfaces in scope:
  • sidebar Jobs
  • callback delivery payloads
  • history/result consumption paths derived from services.comfyui_history
• Current non-goal:
  • no gallery/explorer/runtime flow currently requires direct /api/assets fetches to stay functional.

Decision

• No-go for first-class /api/assets runtime adoption in phase 2.
• OpenClaw keeps /history + /view as the supported runtime contract for normal output handling.
• Asset-api-only identifiers are treated as explicit unsupported contracts rather than implicit fetch targets.

Rationale

1. Current OpenClaw output surfaces still succeed on the existing bounded /view contract, including asset-hash-backed refs.
2. Adding /api/assets as a normal dependency would widen runtime coupling to upstream host behavior without a demonstrated operator need in current features.
3. A silent fallback from asset id only to /api/assets would weaken boundary clarity and make host drift harder to reason about.

Approved phase-2 seam

• Preserve current supported refs exactly:
  • classic refs -> /view?filename=...&type=...
  • asset-hash-backed refs -> /view?filename=blake3:...
  • file-like media refs -> /view fallback/link surfaces when preview metadata is present
  • bounded text refs -> escaped text surfaces, not HTML
• For refs that expose only asset-service identifiers and are not representable through /view:
  • keep them in normalized output payloads
  • mark them as asset_api_required
  • do not auto-fetch /api/assets
  • surface a bounded operator-facing message where relevant

Re-open triggers

Revisit this decision only if one of the following becomes true:

1. A current operator-facing surface cannot complete its supported workflow without direct /api/assets semantics.
2. Upstream ComfyUI stops providing /view-compatible output metadata for supported runtime flows.
3. OpenClaw intentionally adds a new asset-management feature whose documented contract depends on asset-service metadata beyond hash-backed preview resolution.