env.template

# OpenTryOn Environment Configuration Template
# Copy this file to .env and fill in your API keys
# cp env.template .env

# ========================================
# Virtual Try-On Services
# ========================================

# Amazon Nova Canvas (AWS Bedrock)
# Get credentials from: https://console.aws.amazon.com/bedrock/
# Required for: virtual_tryon_nova
AWS_ACCESS_KEY_ID=your_aws_access_key_here
AWS_SECRET_ACCESS_KEY=your_aws_secret_key_here
AMAZON_NOVA_REGION=us-east-1
AMAZON_NOVA_MODEL_ID=amazon.nova-canvas-v1:0

# Kling AI (Kolors Virtual Try-On + Kling 3.0 / 3.0 Omni / 2.5 Turbo video)
# Get API keys from: https://klingai.com/  (Open Platform)
# Docs: https://kling.ai/document-api/guides/get-started/overview
# Required for: vton kling-ai, video-generate kling-v3 / kling-v3-omni / kling-v2-5-turbo
KLING_AI_API_KEY=your_kling_api_key_here
KLING_AI_SECRET_KEY=your_kling_secret_key_here
KLING_AI_BASE_URL=https://api-singapore.klingai.com

# Segmind Try-On Diffusion
# Get API key from: https://www.segmind.com/
# Required for: virtual_tryon_segmind
SEGMIND_API_KEY=your_segmind_api_key_here

# Pruna AI (image generate/edit/upscale, multi-garment try-on, video)
# Get API key from: https://dashboard.pruna.ai/login (contact Pruna to get access)
# Required for: p-image, p-image-ideogram, p-image-edit, p-image-upscale, p-image-tryon, p-video, p-video-replace, p-video-avatar, p-video-animate
PRUNA_API_KEY=your_pruna_api_key_here
# PRUNA_BASE_URL=https://api.pruna.ai  # Optional override

# FASHN AI Virtual Try-On (tryon-max / tryon-v1.6)
# Get API key from: https://app.fashn.ai/api
# Required for: opentryon vton --model fashn-tryon-max / fashn-tryon-v1.6
FASHN_API_KEY=your_fashn_api_key_here
# FASHN_BASE_URL=https://api.fashn.ai  # Optional override

# Google Vertex Virtual Try-On (virtual-try-on-001) — not GEMINI_API_KEY
# Docs: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/imagen/virtual-try-on-001
# Required for: opentryon vton --model google-vton
# Auth: gcloud auth application-default login  (or GOOGLE_APPLICATION_CREDENTIALS)
GOOGLE_CLOUD_PROJECT=your_gcp_project_id
# GOOGLE_CLOUD_LOCATION=global
# GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

# ========================================
# Image Generation Services
# ========================================

# Google Gemini (Nano Banana / Veo / Gemini Omni Flash)
# Get API key from: https://aistudio.google.com/app/apikey
# Required for: generate_image_nano_banana, generate_image_nano_banana_pro,
#   generate_image_nano_banana_2, generate_image_nano_banana_2_lite,
#   opentryon video-generate --model veo / gemini-omni
# Nano Banana 2 Lite (gemini-3.1-flash-lite-image) also powers
# `opentryon vton --model nano-banana-2-lite` (multi-image composition-based try-on)
# Gemini Omni Flash (gemini-omni-flash-preview) powers conversational video
# generation/editing via the Interactions API
GEMINI_API_KEY=your_gemini_api_key_here

# Black Forest Labs (FLUX.2)
# Get API key from: https://docs.bfl.ml/
# Required for: generate_image_flux2_pro, generate_image_flux2_flex
BFL_API_KEY=your_bfl_api_key_here

# Luma AI (Photon & Ray)
# Get Dream Machine key: https://lumalabs.ai/dream-machine/api
# Get Agents API key (Ray 3.2): https://platform.lumalabs.ai/
# Required for: luma-image, luma-video, luma-ray-3.2
LUMA_AI_API_KEY=your_luma_api_key_here
# LUMA_AGENTS_API_KEY=your_luma_agents_api_key_here  # Preferred for Ray 3.2
# LUMA_AGENTS_BASE_URL=https://agents.lumalabs.ai/v1

# OpenAI (GPT Image / Sora)
# Get API key from: https://platform.openai.com/api-keys
# Required for: gpt-image, gpt-image-2.5, gpt-image-2.5-sunburst, sora
OPENAI_API_KEY=your_openai_api_key_here

# BytePlus ModelArk (Seedance video / Seedream image)
# Get API key from: https://console.byteplus.com/ (ModelArk)
# Docs: https://docs.byteplus.com/en/docs/ModelArk/
# Required for: seedance, seedream
ARK_API_KEY=your_byteplus_ark_api_key_here
# BYTEPLUS_ARK_API_KEY=...  # Alias for ARK_API_KEY
# BYTEPLUS_ARK_BASE_URL=https://ark.ap-southeast.bytepluses.com/api/v3

# xAI Grok Imagine (image + video)
# Get API key from: https://console.x.ai/
# Required for: grok-imagine-image, grok-imagine-video
XAI_API_KEY=your_xai_api_key_here
# XAI_BASE_URL=https://api.x.ai/v1

# Ideogram 4.0
# Get API key from: https://developer.ideogram.ai/
# Required for: ideogram
IDEOGRAM_API_KEY=your_ideogram_api_key_here
# IDEOGRAM_BASE_URL=https://api.ideogram.ai

# LTX (Lightricks) — official video API
# Get API key from: https://console.ltx.io
# Required for: opentryon video-generate --model ltx-2.5-api
LTX_API_KEY=your_ltx_api_key_here
# LTX_API_BASE_URL=https://api.ltx.io

# LTX-2.5 local open weights (Diffusers)
# Accept model terms on Hugging Face, then set a token:
#   https://huggingface.co/Lightricks/LTX-2.5-Diffusers
# Required for: opentryon video-generate --model ltx-2.5
# HF_TOKEN=hf_...
# LTX_MODEL_ID=Lightricks/LTX-2.5-Diffusers
# LTX_MODEL_PATH=/path/to/local/snapshot   # optional override

# MiniMax Hailuo 2.3 + MiniMax H3 / H3 Max (official video API)
# Get API key: https://platform.minimax.io/user-center/basic-information/interface-key
# Required for: opentryon video-generate --model hailuo-2.3
#              opentryon video-generate --model minimax-h3
#              opentryon video-generate --model minimax-h3-max
# H3 / H3 Max use the V2 /v2/video_generation surface (Pay-as-you-go). Hailuo 2.3 stays on V1.
MINIMAX_API_KEY=your_minimax_api_key_here
# MINIMAX_API_BASE_URL=https://api.minimax.io

# Fal (third-party MiniMax H3 Max — T2V / I2V / R2V)
# Get API key: https://fal.ai/dashboard/keys
# Required for: opentryon video-generate --model fal-h3-max
# Official MiniMax H3 Max (no R2V) stays MINIMAX_API_KEY / --model minimax-h3-max.
FAL_KEY=your_fal_key_here
# FAL_API_KEY=your_fal_key_here   # alias
# FAL_QUEUE_BASE_URL=https://queue.fal.run

# NVIDIA NIM (build.nvidia.com) — Nemotron Omni + Cosmos 3
# Get API key: https://build.nvidia.com
# Required for: opentryon understand --model nemotron-omni
#              opentryon understand --model cosmos3-reasoner
#              opentryon video-generate --model cosmos3
NVIDIA_API_KEY=your_nvidia_api_key_here
# NVIDIA_API_BASE_URL=https://integrate.api.nvidia.com/v1
# COSMOS3_INFER_URL=https://ai.api.nvidia.com/v1/genai/nvidia/cosmos3-nano
# COSMOS3_INFER_URL=http://127.0.0.1:8000/v1/infer   # self-hosted Generator NIM

# Meta Model API — Muse Image (generate / edit / composition VTON)
# Dashboard: https://dev.meta.ai/docs/authentication
# Required for: opentryon generate|edit|vton --model muse-image
# Muse Video has no developer API or open weights yet (consumer preview only).
MODEL_API_KEY=your_meta_model_api_key_here
# META_MODEL_API_KEY=...   # alias
# MUSE_API_KEY=...         # alias
# META_MODEL_API_BASE_URL=https://api.meta.ai/v1

# MiniMax H3 local open weights (Diffusers ModularPipeline)
# Weights: https://huggingface.co/MiniMaxAI/MiniMax-H3
# Required for: opentryon video-generate --model minimax-h3-local
# Community License excludes US / EU / UK / South Korea for local weights unless
# separately authorized. Hosted API (--model minimax-h3) is globally available.
# HF_TOKEN=hf_...
# MINIMAX_H3_MODEL_ID=MiniMaxAI/MiniMax-H3
# MINIMAX_H3_MODEL_PATH=/path/to/local/snapshot   # optional override

# Alibaba DashScope / Model Studio API
# Get API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Required for: opentryon video-generate --model wan-api
#              opentryon video-generate --model wan-3.0
#              opentryon understand --model qwen3.8-max
#              opentryon understand --model qwen3.8-omni-flash   (adds --audio)
#              opentryon generate|edit|vton --model qwen-image
#              opentryon vton --model outfitanyone-plus   (Beijing-region key)
DASHSCOPE_API_KEY=your_dashscope_api_key_here
# OutfitAnyone-Plus (aitryon-plus) is China Beijing only — not the intl Qwen/Wan host.
# OUTFITANYONE_BASE_URL=https://dashscope.aliyuncs.com/api/v1
# OUTFITANYONE_BASE_URL=https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
# WAN_API_KEY=...  # alias
# International default:
# WAN_API_BASE_URL=https://dashscope-intl.aliyuncs.com/api/v1
# China:
# WAN_API_BASE_URL=https://dashscope.aliyuncs.com/api/v1
# Or workspace URL:
# WAN_API_BASE_URL=https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1
# Qwen OpenAI-compatible chat (understand --model qwen3.8-max):
# QWEN_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1
# China: QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
# Qwen-Image T2I / I2I / VTON (generate|edit|vton --model qwen-image):
# QWEN_IMAGE_BASE_URL=https://dashscope-intl.aliyuncs.com/api/v1
# China: QWEN_IMAGE_BASE_URL=https://dashscope.aliyuncs.com/api/v1

# Z.ai / Zhipu (GLM-5.3-FlashX multimodal understanding)
# Get API key: https://docs.z.ai/api-reference/introduction
# Required for: opentryon understand --model glm-5.3-flashx
ZAI_API_KEY=your_zai_api_key_here
# ZAI_BASE_URL=https://api.z.ai/api/paas/v4  # optional override

# DeepSeek (deepseek-flash multimodal understanding)
# Get API key: https://platform.deepseek.com
# Required for: opentryon understand --model deepseek-flash
DEEPSEEK_API_KEY=your_deepseek_api_key_here
# DEEPSEEK_BASE_URL=https://api.deepseek.com  # optional override

# ElevenLabs (Eleven v4 / Eleven v4 Turbo text-to-speech) — first tts service model
# Get API key: https://elevenlabs.io/app/settings/api-keys
# Required for: opentryon tts --model eleven-v4
#              opentryon tts --model eleven-v4-turbo
ELEVENLABS_API_KEY=your_elevenlabs_api_key_here
# ELEVENLABS_BASE_URL=https://api.elevenlabs.io  # optional override

# Ternary Bonsai 2 27B (PrismML) — local server you run yourself, no cloud key
# Docs: https://docs.prismml.com/bonsai-2-27b
# Required for: opentryon understand --model ternary-bonsai-2-27b
# BONSAI_BASE_URL=http://127.0.0.1:8080/v1  # optional override
# BONSAI_API_KEY=...                        # optional, only if your server enforces auth

# Photoroom Virtual Try-On + Virtual Model (Image Editing API Plus)
# Get API key: https://app.photoroom.com/api
# Required for: opentryon vton --model photoroom-vton
#               opentryon vton --model photoroom-virtual-model
PHOTOROOM_API_KEY=your_photoroom_api_key_here
# Prefix sandbox_ for watermarked tests, or:
# PHOTOROOM_SANDBOX=1

# Wan 2.2 local open weights (Diffusers)
# Required for: opentryon video-generate --model wan-2.2
# Wan 3.0 has no official open weights; self-host stays on 2.2.
# WAN_MODEL_ID=Wan-AI/Wan2.2-TI2V-5B-Diffusers
# WAN_MODEL_PATH=/path/to/local/snapshot

# Runway Gen-4.5 (official API — no open weights)
# Get API key: https://dev.runwayml.com/
# Required for: opentryon video-generate --model runway-gen4.5
RUNWAYML_API_SECRET=your_runway_api_secret_here
# RUNWAY_API_KEY=...  # alias
# RUNWAY_API_BASE_URL=https://api.dev.runwayml.com

# ========================================
# Multimodal Understanding Services
# ========================================

# Moonshot AI (Kimi K2.6, K2.7 Code, and K3)
# Get API key from: https://platform.kimi.ai/console/api-keys
# Required for: opentryon understand --model kimi-k2.6 / kimi-k2.7-code / kimi-k3
# Text, image, and video understanding -- general-purpose, not fashion-specific.
MOONSHOT_API_KEY=your_moonshot_api_key_here
# KIMI_BASE_URL=https://api.moonshot.ai/v1  # Optional override

# Tencent Hy4 preview (TokenHub LLM)
# Get API key from: TokenHub console (Tencent Cloud)
# Docs: https://www.tencentcloud.com/document/product/1300/80695
# Required for: opentryon understand --model hy4-preview
TOKENHUB_API_KEY=your_tokenhub_api_key_here
# TOKENHUB_BASE_URL=https://tokenhub-intl.tencentcloudmaas.com/v1
# TENCENT_TOKENHUB_API_KEY=  # alias for TOKENHUB_API_KEY
# Local vLLM/SGLang twin (no TokenHub key):
# Required for: opentryon understand --model hy4-preview-local
# HY4_BASE_URL=http://127.0.0.1:8000/v1
# HY4_API_KEY=EMPTY

# Qwen3.8 local open weights (Transformers)
# Required for: opentryon understand --model qwen3.8
# Default HF id: Qwen/Qwen3.8-27B (needs recent transformers + substantial VRAM)
# QWEN38_MODEL_ID=Qwen/Qwen3.8-27B

# DeepSeek-VL2 local open weights (Transformers + DeepSeek's own deepseek_vl2 package)
# Required for: opentryon understand --model deepseek-vl2
# No first-party hosted API exists for this model.
# Default HF id: deepseek-ai/deepseek-vl2-tiny (single-GPU friendly)
# Needs: pip install "git+https://github.com/deepseek-ai/DeepSeek-VL2.git"
# DEEPSEEK_VL2_MODEL_ID=deepseek-ai/deepseek-vl2-tiny

# DeepSeek-OCR local open weights (Transformers)
# Required for: opentryon understand --model deepseek-ocr
# No first-party hosted API exists for this model.
# Default HF id: deepseek-ai/DeepSeek-OCR (needs flash-attn; see model card for exact
# torch/transformers/flash-attn pins, newer than this repo's shared opentryon[local] pin)
# DEEPSEEK_OCR_MODEL_ID=deepseek-ai/DeepSeek-OCR

# Qwen-Image local open weights (Diffusers)
# Required for: opentryon generate|edit|vton --model qwen-image-local
# Default T2I: Qwen/Qwen-Image-2512  Edit/VTON: Qwen/Qwen-Image-Edit-2511
# Needs recent diffusers (QwenImagePipeline / QwenImageEditPlusPipeline) + CUDA
# 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

# Leffa local VTON (CVPR 2025)
# Required for: opentryon vton --model leffa
# Weights: franciszzj/Leffa  Code: https://github.com/franciszzj/Leffa (MIT)
# LEFFA_HOME=/path/to/clone/of/franciszzj/Leffa
# LEFFA_CKPT=/path/to/hf/snapshot

# CatVTON local VTON (ICLR 2025) — CC BY-NC-SA 4.0, not for commercial D2C
# Required for: opentryon vton --model catvton
# Weights: zhengchong/CatVTON
# CATVTON_ATTN_CKPT=zhengchong/CatVTON
# CATVTON_BASE_MODEL=runwayml/stable-diffusion-inpainting
# If the runwayml inpainting repo is gated:
# CATVTON_BASE_MODEL=botp/stable-diffusion-v1-5-inpainting

# ========================================
# Preprocessing Models
# ========================================

# U2Net Cloth Segmentation Checkpoint
# Download from: https://github.com/levindabhi/cloth-segmentation/tree/master
# Required for: segment_garment, extract_garment
# Example path: /path/to/cloth_segm_u2net_latest.pth
U2NET_CLOTH_SEG_CHECKPOINT_PATH=

# ========================================
# Optional: API Server Configuration
# ========================================

# API Server Port (default: 8000)
# API_SERVER_PORT=8000

# API Server Host (default: 0.0.0.0)
# API_SERVER_HOST=0.0.0.0

# Enable Debug Mode (default: False)
# DEBUG=False

# ========================================
# Agents (planner / Studio chat)
# ========================================

# Planner is the MCP / Studio chat entrypoint. A cheap model classifies intent,
# then the planner calls invoke_model on a filtered registry slice (the same
# tools capability screens use). Image/VTON/video keys above are unchanged.
#
# openai | anthropic | google
OPENTRYON_AGENT_LLM_PROVIDER=openai
# Cheap intent model (defaults: gpt-4o-mini / claude-3-5-haiku-latest / gemini-2.0-flash)
OPENTRYON_PLANNER_LLM_MODEL=gpt-4o-mini
# Fallback if OPENTRYON_PLANNER_LLM_MODEL is unset
# OPENTRYON_AGENT_LLM_MODEL=gpt-4o-mini
# Optional OpenAI-compatible host (Moonshot, DashScope compatible mode, …)
# OPENTRYON_AGENT_LLM_BASE_URL=https://api.moonshot.ai/v1
# OPENTRYON_AGENT_LLM_API_KEY=  # else OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY
# TryOn Studio Connect can set these via MCP list_api_keys / set_api_keys
# (written here, never stored in Studio).

# ========================================
# Notes
# ========================================

# Minimum Required Services (for basic functionality):
#   - At least ONE virtual try-on service (Nova Canvas, Kling AI, or Segmind)
#   - At least ONE image generation service (Gemini, FLUX.2, or Luma AI)

# Optional Services:
#   - Luma AI: For video generation and additional image generation
#   - U2Net: For local garment preprocessing (can use API-based preprocessing instead)

# Service Configuration Status:
#   ✓ Configured: API key is set and validated
#   ✗ Not configured: API key is missing or invalid
#   Run the MCP server to see current configuration status

# To use this template:
# 1. Copy this file: cp env.template .env
# 2. Fill in your API keys in the .env file
# 3. Never commit the .env file (it's in .gitignore)