AI Fashion Studio

AI Fashion Studio

AI Fashion Studio is an API-first ComfyUI custom-node pack for turning apparel product images into evaluated on-model imagery and short fashion videos. ComfyUI remains the visual workflow editor and orchestration layer; expensive image and video inference is delegated to replaceable hosted providers.

Product flow

Product images + model reference + creative direction
  -> product normalization and analysis
  -> virtual try-on candidates
  -> optional creative scene edit
  -> garment-fidelity evaluation and ranking
  -> image-to-video generation and evaluation
  -> local assets and a structured run manifest

Product fidelity takes priority over creative quality. Important intermediate assets will remain previewable, provider response formats will stay inside adapters, and exported workflows will never contain provider secrets.

Current status

Milestones 0, 1, and 2 are complete. The project now includes:

• A directly installable ComfyUI V3 node pack tested on ComfyUI 0.28.0.
• Environment-only configuration with bounded defaults.
• Eight zero-cost workflow nodes covering product setup through video export.
• Deterministic mock analysis, candidate generation, scoring, ranking, and motion.
• Real OpenAI product analysis, spec-aware candidate QA, and creative scene editing behind provider-dropdown nodes.
• Structured-output contracts, per-run cost tracking with a configurable ceiling, and bounded retries for transient API failures.
• Native ComfyUI IMAGE and VIDEO outputs with previewable intermediates.
• Atomic local export of inputs, candidates, selected image, MP4, and manifest JSON.
• Importable visual and API-format mock workflows plus a live analysis workflow.

Virtual try-on (FASHN) and real image-to-video are not included yet; those stages still use the mock provider. See PROJECT_TRACKING.md for implementation status and evidence.

Planned architecture

ComfyUI workflows
  -> thin AI Fashion Studio nodes
  -> shared validation, retry, polling, cost, and asset services
  -> normalized provider interfaces
  -> OpenAI / FASHN / selected video provider / mock provider
  -> versioned local run manifest

The MVP calls provider APIs directly from custom nodes. A FastAPI gateway is deferred until multi-worker credentials, durable callbacks, centralized quotas, or multi-user execution justify it.

Repository layout

__init__.py                  ComfyUI package entrypoint
ai_fashion_studio/           Application and node implementation
tests/                       Unit and compatibility tests
docs/decisions/              Architecture decision records
workflows/                   UI and API workflow JSON (later milestones)
PROJECT_TRACKING.md          Milestone checklist and evidence

Development setup

Python 3.11 through 3.13 is supported. ComfyUI supplies the comfy_api package at runtime; the ordinary unit tests do not require ComfyUI to be installed.

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
python -m pytest

To try the node pack in an existing ComfyUI checkout during Milestone 0, link or clone this repository as one directory under ComfyUI/custom_nodes, install its requirements in the ComfyUI Python environment, and restart ComfyUI. The node should appear as AI Fashion Studio / System / Diagnostics.

Configuration

Copy .env.example only as a reference for the environment variables your launch mechanism should provide. The node pack does not embed secrets in workflow files and does not print credential values.

Milestone 0 variables:

| Variable | Default | Purpose | | --- | --- | --- | | AIFS_PROVIDER_MODE | diagnostic | Runtime mode | | AIFS_OUTPUT_ROOT | output/ai-fashion-studio | Run artifact root | | AIFS_MAX_CANDIDATES | 4 | Hard candidate ceiling | | AIFS_MAX_RUN_COST_USD | 10.00 | Per-run cost ceiling | | AIFS_LOG_LEVEL | INFO | Application log level | | AIFS_OPENAI_ANALYSIS_MODEL | gpt-5.5 | Analysis and image-QA model | | AIFS_OPENAI_EDIT_MODEL | gpt-image-2 | Scene-edit model | | AIFS_OPENAI_TIMEOUT_SECONDS | 300 | Per-call timeout | | AIFS_OPENAI_MAX_RETRIES | 3 | Transient-failure retries |

Milestone 2 variables:

| Variable | Purpose | | --- | --- | | OPENAI_API_KEY | OpenAI credential; process environment only | | AIFS_ENABLE_PAID_TESTS | Set to 1 to unskip the paid smoke test |

Provider credentials will be added milestone by milestone and read from the process environment only.

Run the mock vertical slice in ComfyUI

1. Restart ComfyUI after updating the node pack.
2. Open workflows/ui/mock_vertical_slice.json through ComfyUI's workflow menu or drag it onto the canvas.
3. Choose a product image in the first Load Image node.
4. Choose a model reference in the second Load Image node.
5. Adjust product text, candidate count, seed, duration, or FPS if desired.
6. Run the workflow.

The workflow previews the source product, all candidates, and the selected image. Export Run writes results beneath output/ai-fashion-studio/<run-id>/. The mock video is a deterministic motion preview for orchestration testing; it is not generative inference.

Run the live analysis slice in ComfyUI

1. Install the pack's requirements into the ComfyUI Python environment (pip install -r requirements.txt) and restart ComfyUI.
2. Provide OPENAI_API_KEY in the ComfyUI process environment.
3. Open workflows/ui/live_analysis_slice.json, choose the two input images, and run.

Analyze Product (gpt-5.5, structured output) and Evaluate Image Candidates (spec-aware QA) call OpenAI; Creative Scene Edit (gpt-image-2) edits the selected image with garment guardrails from the specification. Candidate generation and video still use the free mock provider until Milestones 3 and 4. Every live node has a provider dropdown, so the same graph runs zero-cost by switching each stage back to mock. Spend is tracked per run and stops at AIFS_MAX_RUN_COST_USD.

The paid smoke test is gated and never runs by default:

AIFS_ENABLE_PAID_TESTS=1 OPENAI_API_KEY=sk-... python -m pytest tests/paid -m paid

Headless validation and smoke testing:

python scripts/validate_workflows.py

PYTHONPATH="/path/to/ComfyUI:$PWD" \
  /path/to/ComfyUI/.venv/bin/python scripts/run_mock_smoke_test.py

See docs/workflow_guide.md for node and output details.

Compatibility baseline

The extension pins comfy_api.v0_0_2 instead of the moving comfy_api.latest alias. Milestone 0 is verified against ComfyUI 0.28.0 on Python 3.13.12; Registry metadata therefore declares requires-comfyui >=0.28.0. See ADR 002.

Testing policy

• Unit and mock tests must never spend API credits.
• Paid tests will use the paid marker and require an explicit environment gate.
• Workflow validation will reject embedded secrets before workflow files are accepted.
• Provider-specific response fixtures will be sanitized before committing.

Non-goals for the MVP

The MVP does not include a customer web UI, authentication, commerce integrations, billing, distributed GPU infrastructure, custom-model training, or mandatory local diffusion/video weights.

Open project decisions

• Reserve the Comfy Registry publisher ID and replace placeholder repository URLs.
• Select a repository license.
• Record the first supported ComfyUI release or commit after local compatibility testing.
• Confirm official Seedance API access or use FASHN Image to Video for the first real video adapter.