Skip to main content

Configuration

Learn how to configure OpenTryOn for your specific needs. The same opentryon/.env file is read by the CLI, the MCP server, and TryOn Studio Connect (Studio never stores keys itself).

Environment Variables​

OpenTryOn uses environment variables for configuration. Create a .env file in your project root:

Preprocessing (Required for Local Preprocessing)​

# U2Net Model Checkpoints (Required for garment/human segmentation)
U2NET_CLOTH_SEG_CHECKPOINT_PATH=path/to/cloth_segm.pth
U2NET_SEGM_CHECKPOINT_PATH=path/to/u2net.pth

# Optional: GPU Configuration
CUDA_VISIBLE_DEVICES=0

# Optional: Logging
LOG_LEVEL=INFO

API Integrations (Optional - Only configure APIs you plan to use)​

# Segmind Try-On Diffusion API
SEGMIND_API_KEY=your_segmind_api_key

# Kling AI Virtual Try-On API
KLING_AI_API_KEY=your_kling_api_key
KLING_AI_SECRET_KEY=your_kling_secret_key
KLING_AI_BASE_URL=https://api-singapore.klingai.com # Optional

# Amazon Nova Canvas (AWS Bedrock)
AWS_ACCESS_KEY_ID=your_aws_access_key
AWS_SECRET_ACCESS_KEY=your_aws_secret_key
AMAZON_NOVA_REGION=us-east-1 # Options: us-east-1, ap-northeast-1, eu-west-1
AMAZON_NOVA_MODEL_ID=amazon.nova-canvas-v1:0 # Optional

# Google Gemini (Nano Banana Image Generation)
GEMINI_API_KEY=your_gemini_api_key

# Google Vertex Virtual Try-On (virtual-try-on-001) — not GEMINI_API_KEY
GOOGLE_CLOUD_PROJECT=your_gcp_project_id
# GOOGLE_CLOUD_LOCATION=global

# BFL AI (FLUX.2 Image Generation)
BFL_API_KEY=your_bfl_api_key

# Moonshot AI (Kimi K2.6 / K2.7 Code multimodal understanding)
MOONSHOT_API_KEY=your_moonshot_api_key

# Reflection Beam (understand beam — text chat, Beam-1.0-501B-A23B)
REFLECTION_API_KEY=your_reflection_api_key
# REFLECTION_BASE_URL=https://api.reflection.ai/openai/v1

# Poolside Laguna (understand laguna-xs.2 / laguna-xs.2.1 / laguna-m.1 — text chat)
POOLSIDE_API_KEY=your_poolside_api_key
# POOLSIDE_BASE_URL=https://inference.poolside.ai/v1

# Arcee Trinity (understand trinity-large / trinity-large-thinking / trinity-mini — text chat)
ARCEE_API_KEY=your_arcee_api_key
# ARCEEAI_API_KEY= # alias
# ARCEE_BASE_URL=https://api.arcee.ai/api/v1
# trinity-nano (local vLLM/SGLang, not hosted):
# TRINITY_BASE_URL=http://127.0.0.1:8000/v1

# Recraft V3 (generate / edit / bg-remove recraft-v3)
RECRAFT_API_TOKEN=your_recraft_api_token
# RECRAFT_API_KEY= # alias
# RECRAFT_BASE_URL=https://external.api.recraft.ai/v1

# Tencent TokenHub (Hy4 preview LLM) — not Moonshot / DashScope
TOKENHUB_API_KEY=your_tokenhub_api_key
# TOKENHUB_BASE_URL=https://tokenhub-intl.tencentcloudmaas.com/v1

# Alibaba DashScope (Wan, Qwen3.8-Max, Qwen3.8-Omni-Flash, Qwen-Image, OutfitAnyone-Plus)
DASHSCOPE_API_KEY=your_dashscope_api_key

# Z.ai / Zhipu (GLM-5.3-FlashX multimodal understanding)
ZAI_API_KEY=your_zai_api_key
# ZAI_BASE_URL=https://api.z.ai/api/paas/v4

# DeepSeek (deepseek-flash multimodal understanding — image only, no video)
DEEPSEEK_API_KEY=your_deepseek_api_key
# DEEPSEEK_BASE_URL=https://api.deepseek.com

# ElevenLabs (Eleven v4 / Eleven v4 Turbo text-to-speech — first tts service model)
ELEVENLABS_API_KEY=your_elevenlabs_api_key
# ELEVENLABS_BASE_URL=https://api.elevenlabs.io

# Anthropic (Claude Haiku 5.5 understanding; also the Studio chat planner)
ANTHROPIC_API_KEY=your_anthropic_api_key

# Typesafe AI (Jev decision model -- early access)
TYPESAFE_API_KEY=your_typesafe_api_key
# TYPESAFE_BASE_URL=https://api.typesafe.ai

# Photoroom Virtual Try-On + Virtual Model
PHOTOROOM_API_KEY=your_photoroom_api_key

# MiniMax Hailuo 2.3 + MiniMax H3 / H3 Max video (same key; H3 uses V2)
MINIMAX_API_KEY=your_minimax_api_key

# Fal (third-party MiniMax H3 Max — T2V / I2V / R2V)
FAL_KEY=your_fal_key

# NVIDIA NIM (Nemotron Omni understand, Cosmos 3 Reasoner, Cosmos 3 Generator)
NVIDIA_API_KEY=your_nvidia_api_key
# Self-hosted Cosmos 3 certified NIM (cosmos3-nano-t2i, cosmos3-nano-v2v, cosmos3-nano-droid)
# COSMOS3_NIM_URL=http://127.0.0.1:8010/v1/infer

# Moondream Cloud (understand + detect: moondream-3.1, moondream-3-preview)
MOONDREAM_API_KEY=your_moondream_api_key

# Clad body measurements (measure clad-body-photo / clad-body-questionnaire)
CLAD_API_KEY=your_clad_api_key

# Meta Model API (Muse Image generate/edit/vton)
MODEL_API_KEY=your_meta_model_api_key

# Pruna AI (P-Image, P-Image-Ideogram, P-Image-Edit, try-on, P-Video family incl. P-Video-2-Pro)
PRUNA_API_KEY=your_pruna_api_key

Local server models (Optional — no cloud key)​

# Ternary Bonsai 2 27B — you run its llama.cpp/MLX server yourself;
# OpenTryOn is just an OpenAI-compatible client against it.
# BONSAI_BASE_URL=http://127.0.0.1:8080/v1
# BONSAI_API_KEY=... # only if your server enforces auth

Datasets (Optional - Only if using HuggingFace datasets)​

# HuggingFace datasets cache (for Subjects200K)
# Defaults to ~/.cache/huggingface/datasets if not set
HF_DATASETS_CACHE=path/to/cache

Planner / Studio chat (optional — only if you use planner_agent)​

The cheap intent model is separate from image/VTON/video keys. Studio Agent chat calls MCP planner_agent; set these on the MCP host and restart the server. See Planner Agent and TryOn Studio.

OPENTRYON_AGENT_LLM_PROVIDER=openai
OPENTRYON_PLANNER_LLM_MODEL=gpt-4o-mini
# OPENAI_API_KEY=... # or ANTHROPIC_API_KEY / GEMINI_API_KEY

Note: You only need to configure the APIs and features you plan to use. For example:

  • Preprocessing only: Only U2Net checkpoints required
  • API integrations only: Only API keys required (no local models needed)
  • Datasets only: No configuration needed (automatic download/caching)

Loading Environment Variables​

Always load environment variables before using OpenTryOn:

from dotenv import load_dotenv
load_dotenv()

# Now import and use OpenTryOn modules
from tryon.preprocessing import segment_garment
from tryon.api import SegmindVTONAdapter
from tryon.datasets import FashionMNIST

Getting API Keys​

Segmind Try-On Diffusion​

  1. Sign up at Segmind API Portal
  2. Obtain your API key from the dashboard
  3. Add to .env: SEGMIND_API_KEY=your_key

Kling AI Virtual Try-On​

  1. Sign up at Kling AI Developer Portal
  2. Obtain API key (access key) and secret key
  3. Add to .env:
    KLING_AI_API_KEY=your_api_key
    KLING_AI_SECRET_KEY=your_secret_key

Amazon Nova Canvas​

  1. Set up AWS account with Bedrock access
  2. Enable Nova Canvas in AWS Bedrock console (Model access section)
  3. Configure AWS credentials (via .env or AWS CLI):
    AWS_ACCESS_KEY_ID=your_access_key
    AWS_SECRET_ACCESS_KEY=your_secret_key
    AMAZON_NOVA_REGION=us-east-1

Google Gemini (Nano Banana)​

  1. Sign up at Google AI Studio
  2. Obtain API key from API Keys page
  3. Add to .env: GEMINI_API_KEY=your_key

BFL AI (FLUX.2)​

  1. Sign up at BFL AI
  2. Obtain your API key from the BFL AI dashboard
  3. Add to .env: BFL_API_KEY=your_key

Moonshot AI (Kimi K2.6 / K2.7 Code)​

  1. Sign up at platform.kimi.ai
  2. Obtain your API key from the API Keys console
  3. Add to .env: MOONSHOT_API_KEY=your_key

Tencent TokenHub (Hy4 preview)​

  1. Follow TokenHub Chat Completions and create an API key
  2. Add to .env: TOKENHUB_API_KEY=your_key
  3. Optional: TENCENT_TOKENHUB_API_KEY (alias) or TOKENHUB_BASE_URL (default international endpoint)
  4. Local weights twin (hy4-preview-local) does not use this key — serve vLLM/SGLang and set HY4_BASE_URL

See Hy4 TokenHub and Hy4 local.

Alibaba DashScope (Qwen3.8, Qwen-Image, Wan)​

  1. Sign up at Alibaba Cloud Model Studio

  2. Create an API key for your region

  3. Add to .env:

    DASHSCOPE_API_KEY=your_key
    # Optional: QWEN_BASE_URL for Qwen3.8-Max chat (OpenAI-compatible)
    # Optional: QWEN_IMAGE_BASE_URL for Qwen-Image T2I / I2I / VTON

    Same key covers understand --model qwen3.8-max, understand --model qwen3.8-omni-flash (adds --audio), generate|edit|vton --model qwen-image, video-generate --model wan-api / wan-3.0, and Beijing-region vton --model outfitanyone-plus (aitryon-plus). International keys used for Qwen/Wan do not unlock OutfitAnyone-Plus.

    Local open-weight twin (pip install opentryon[local], CUDA, recent Diffusers):

    # Optional overrides; defaults are the official HF snapshots
    # QWEN_IMAGE_LOCAL_MODEL_ID=Qwen/Qwen-Image-2512
    # QWEN_IMAGE_EDIT_MODEL_ID=Qwen/Qwen-Image-Edit-2511
    # QWEN_IMAGE_LOCAL_PATH=/path/to/local/t2i-snapshot
    # QWEN_IMAGE_EDIT_PATH=/path/to/local/edit-snapshot

    CLI: opentryon generate|edit|vton --model qwen-image-local. See Qwen-Image local.

Local dedicated VTON (Leffa / CatVTON)​

No API key. Needs pip install opentryon[local] and a CUDA GPU.

  • vton --model leffa — Leffa. Optional LEFFA_HOME / LEFFA_CKPT.
  • vton --model catvton — CatVTON (CC BY-NC-SA 4.0). Optional CATVTON_BASE_MODEL if the SD 1.5 inpainting repo is gated.

Photoroom (Virtual Try-On / Virtual Model)​

  1. Activate the API at app.photoroom.com/api

  2. Add to .env: PHOTOROOM_API_KEY=your_key

  3. Optional watermarked tests: prefix the key with sandbox_ or set PHOTOROOM_SANDBOX=1

    Covers vton --model photoroom-vton (shopper photo + product) and vton --model photoroom-virtual-model (flat-lay → on-model). Plus / Enterprise Image Editing API. See Photoroom.

MiniMax (Hailuo 2.3 + H3 + H3 Max)​

  1. Sign up at MiniMax Open Platform

  2. Create an interface key from API keys

  3. Add to .env: MINIMAX_API_KEY=your_key

    Same key covers video-generate --model hailuo-2.3 (V1), video-generate --model minimax-h3 (V2 H3), and video-generate --model minimax-h3-max (V2 H3 Max, fast). H3 on the API is billed as pay-as-you-go video.

    Local open-weight twin (pip install opentryon[local], CUDA, Diffusers from main): --model minimax-h3-local. The Community License for those weights excludes US/EU/UK/South Korea unless separately authorized. See MiniMax H3 local.

Fal (MiniMax H3 Max)​

  1. Create a key at Fal API keys

  2. Add to .env: FAL_KEY=your_key (FAL_API_KEY is an alias)

    Covers video-generate --model fal-h3-max (T2V / I2V / R2V) and video-generate --model fal-h3-max-lipsync (portrait + audio → lip-synced video). This is a third-party hoster, not MiniMax’s V2 API. First-party Max remains --model minimax-h3-max. See MiniMax H3 Max (Fal).

Z.ai / Zhipu (GLM-5.3-FlashX)​

  1. Create a key at Z.ai / the Z.ai API docs

  2. Add to .env: ZAI_API_KEY=your_key

    Covers understand --model glm-5.3-flashx (text/image/video understanding, 200 tok/s serving tier of GLM-5.3-Flash). See GLM-5.3-FlashX.

DeepSeek (deepseek-flash)​

  1. Create a key at platform.deepseek.com

  2. Add to .env: DEEPSEEK_API_KEY=your_key

    Covers understand --model deepseek-flash (text/image understanding — no video, unlike Kimi/Qwen3.8/GLM). Cheapest frontier-class VLM available; 1M context. See DeepSeek-V4.1-Flash.

DeepSeek-VL2 / DeepSeek-OCR (local, no cloud key)​

No API key. Needs pip install opentryon[local] and a CUDA GPU. No first-party hosted API exists for either model — local is the only path.

  • understand --model deepseek-vl2 — DeepSeek-VL2. Also needs DeepSeek's own deepseek_vl2 package (not on PyPI): pip install "git+https://github.com/deepseek-ai/DeepSeek-VL2.git". Optional DEEPSEEK_VL2_MODEL_ID.
  • understand --model deepseek-ocr — DeepSeek-OCR. Also needs flash-attn; the model card pins torch==2.6.0/transformers==4.46.3, newer than this repo's shared opentryon[local] pin. Optional DEEPSEEK_OCR_MODEL_ID.

ElevenLabs (eleven-v4 / eleven-v4-turbo)​

  1. Create a key at elevenlabs.io/app/settings/api-keys

  2. Add to .env: ELEVENLABS_API_KEY=your_key

    Covers tts --model eleven-v4 and tts --model eleven-v4-turbo — OpenTryOn's first tts service (text -> speech audio, no image/video needed). Default voice is ElevenLabs' premade "Rachel"; override with --voice-id. See ElevenLabs Eleven v4 / v4 Turbo.

Gemini 3.8 Flash (gemini-3.8-flash / gemini-3.8-flash-tts / gemini-3.8-flash-lite-tts)​

Uses the same GEMINI_API_KEY as Nano Banana, Veo and Gemini Omni (optional GEMINI_API_BASE_URL). Covers understand --model gemini-3.8-flash and tts --model gemini-3.8-flash-tts / gemini-3.8-flash-lite-tts, and embed --model gemini-embedding-2. See Gemini 3.8 Flash and Gemini Embedding 2.

Anthropic (claude-haiku-5-5)​

  1. Create a key at console.anthropic.com/settings/keys

  2. Add to .env: ANTHROPIC_API_KEY=your_key

    Covers understand --model claude-haiku-5-5 (text/image, no video) and is the same key Studio chat uses when OPENTRYON_AGENT_LLM_PROVIDER=anthropic. See Claude Haiku 5.5.

Typesafe AI (jev)​

  1. Request access at console.typesafe.ai (early access; new sign-ups were paused 2026-09-22)

  2. Add to .env: TYPESAFE_API_KEY=your_key (optional TYPESAFE_BASE_URL for an OpenRouter/Vercel/DigitalOcean-compatible gateway)

    Covers decide --model jev. See Typesafe Jev.

Perplexity (pplx-decider)​

  1. Create a key at perplexity.ai/account/api/keys

  2. Add to .env: PERPLEXITY_API_KEY=your_key

    Covers decide --model pplx-decider. See Open decision models.

Cloudflare Workers AI (clef)​

  1. Create a Workers AI API token at dash.cloudflare.com/profile/api-tokens and copy your account id

  2. Add to .env: CLOUDFLARE_API_TOKEN=your_token and CLOUDFLARE_ACCOUNT_ID=your_account_id

    Covers decide --model clef (Clef and Clef-flash). Kev via OpenRouter (decide --model kev-openrouter) uses OPENROUTER_API_KEY. Self-hosted servers take KEV_BASE_URL, CLEF_BASE_URL, PPLX_DECIDER_BASE_URL and AUTOTRUST_JEV_BASE_URL. See Open decision models.

FASHN catalogue endpoints (hosted)​

Uses the same FASHN_API_KEY as vton --model fashn-tryon-max. Covers fashn-product-to-model, fashn-model-create, fashn-model-swap, fashn-face-to-model, fashn-reframe, fashn-edit, fashn-image-to-video and fashn-bg-remove. See FASHN.

FLUX.2-klein-4B try-on / try-on safety classifier (local, no cloud key)​

No API key. klein-4b-tryon needs a CUDA GPU, pip install git+https://github.com/huggingface/diffusers.git peft accelerate (overrides KLEIN_TRYON_LORA_ID, KLEIN_TRYON_BASE_ID). tryon-safety-classifier needs pip install open_clip_torch safetensors (override TRYON_SAFETY_MODEL_ID). See klein try-on and safety classifier.

Fashion Florence / Extract-Outfit (local, no cloud key)​

No API key. pip install opentryon[local]; Extract-Outfit also needs pip install -U peft diffusers transformers accelerate and a CUDA GPU (Qwen-Image-Edit-2511 base). Optional overrides: FASHION_FLORENCE_MODEL_ID, EXTRACT_OUTFIT_LORA_ID. See Fashion Florence and Extract-Outfit.

Fashion retrieval embeddings (local, no cloud key)​

No API key. pip install opentryon[local] plus pip install open_clip_torch for Marqo-FashionSigLIP and MODA (ZooClaw-FashionSigLIP2 needs only transformers). Covers embed --model marqo-fashionsiglip | moda-fashion-distilled | moda-pro-lite | zooclaw-fashionsiglip2. See Fashion embeddings.

FASHN VTON v1.5 (local, no cloud key)​

No API key. pip install opentryon[local] plus pip install "git+https://github.com/fashn-AI/fashn-vton-1.5.git". Weights (~2 GB) auto-download to ~/.cache/opentryon/fashn-vton-1.5; set FASHN_VTON_WEIGHTS_DIR to use your own folder. Covers vton --model fashn-vton-1.5. See FASHN VTON v1.5.

Liquid d1 / EmbeddingGemma 2 / pplx-embed-v2-late (local, no cloud key)​

No API key. Need pip install opentryon[local] plus newer libraries in a separate env (transformers>=5.15 for d1; sentence-transformers for the embedders — >=6.0.0 for pplx). Optional overrides: LIQUID_D1_MODEL_ID, EMBEDDINGGEMMA_MODEL_ID, PPLX_EMBED_MODEL_ID. See Liquid d1, EmbeddingGemma 2, pplx-embed-v2-late.

Ternary Bonsai 2 27B (local server, no cloud key)​

No API key. Start the model's own llama.cpp (PrismML fork, prism-b10658+) or MLX server yourself, then point OpenTryOn at it:

# BONSAI_BASE_URL=http://127.0.0.1:8080/v1   # default
# BONSAI_API_KEY=... # only if your server enforces auth

CLI: opentryon understand --model ternary-bonsai-2-27b. See Ternary Bonsai 2 27B.

NVIDIA NIM (Nemotron / Cosmos)​

  1. Create a key at build.nvidia.com

  2. Add to .env: NVIDIA_API_KEY=your_key

    Same key covers understand --model nemotron-omni, understand --model nemotron-3.5-super-vl, understand --model cosmos3-reasoner, and video-generate --model cosmos3. Optional COSMOS3_INFER_URL points a self-hosted Generator NIM at http://127.0.0.1:8000/v1/infer. See NVIDIA NIM.

Meta Model API (Muse Image)​

  1. Create a key in the Model API dashboard

  2. Add to .env: MODEL_API_KEY=your_key (aliases: META_MODEL_API_KEY, MUSE_API_KEY)

    Covers generate|edit|vton --model muse-image. Muse Video has no developer API or open weights yet.

Configuration Options​

GPU Configuration​

Specify which GPU to use:

import os
os.environ["CUDA_VISIBLE_DEVICES"] = "0" # Use first GPU

Model Checkpoint Paths​

Set custom checkpoint paths:

import os
os.environ["U2NET_CLOTH_SEG_CHECKPOINT_PATH"] = "/custom/path/cloth_segm.pth"
os.environ["U2NET_SEGM_CHECKPOINT_PATH"] = "/custom/path/u2net.pth"

Logging Configuration​

Configure logging level:

import logging
logging.basicConfig(level=logging.INFO)

Default Settings​

OpenTryOn uses sensible defaults:

  • Image Size: Automatically resized based on model requirements
  • Batch Size: 1 (can be adjusted for batch processing)
  • Device: Auto-detects CUDA if available, falls back to CPU
  • Normalization: Images normalized to [-1, 1] range

Custom Configuration​

You can override defaults when calling functions:

from tryon.preprocessing.extract_garment_new import extract_garment
from PIL import Image
import torch

# Use specific device
device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")

# Load model once for efficiency
net = load_cloth_segm_model(device, os.environ.get("U2NET_CLOTH_SEGM_CHECKPOINT_PATH"))

# Use pre-loaded model
image = Image.open("garment.jpg")
garments = extract_garment(
image=image,
cls="upper",
resize_to_width=400,
net=net, # Reuse model
device=device
)

Quick Configuration Examples​

Preprocessing Only​

U2NET_CLOTH_SEG_CHECKPOINT_PATH=./models/cloth_segm.pth
U2NET_SEGM_CHECKPOINT_PATH=./models/u2net.pth

API Integrations Only (No Local Models)​

SEGMIND_API_KEY=your_segmind_key
GEMINI_API_KEY=your_gemini_key
BFL_API_KEY=your_bfl_key

Full Setup (Preprocessing + APIs + Datasets)​

# Preprocessing
U2NET_CLOTH_SEG_CHECKPOINT_PATH=./models/cloth_segm.pth
U2NET_SEGM_CHECKPOINT_PATH=./models/u2net.pth

# APIs
SEGMIND_API_KEY=your_segmind_key
KLING_AI_API_KEY=your_kling_key
KLING_AI_SECRET_KEY=your_kling_secret
GEMINI_API_KEY=your_gemini_key
BFL_API_KEY=your_bfl_key
AWS_ACCESS_KEY_ID=your_aws_key
AWS_SECRET_ACCESS_KEY=your_aws_secret
AMAZON_NOVA_REGION=us-east-1

Best Practices​

  1. Always use .env file: Never commit API keys or paths to version control
  2. Load environment variables first: Before importing any OpenTryOn modules
  3. Use absolute paths: For checkpoint paths to avoid issues
  4. Check GPU availability: Verify CUDA before running intensive operations
  5. Only configure what you need: Don't add API keys for services you won't use
  6. Keep .env in .gitignore: Protect your credentials

Next Steps​