Snapmydesign (SMD) VTON SDK

Official Python SDK for the Snapmydesign (SMD) Virtual Try-On (VTON) API. This SDK provides a simple, clean, and fully-typed interface (supporting both synchronous and asynchronous usage) to interact with VTON generation, image uploads, user credits, subscriptions, and API key management.

---

🚀 Features

• Double-Flavored Client: Native support for both synchronous (VTONClient) and asynchronous (AsyncVTONClient) flows.
• Robust Exception Mapping: Maps HTTP error statuses (like 401, 403, 404, 501) directly to descriptive Python exception classes.
• Multi-Format Image Upload: Upload files directly by path string, pathlib.Path, binary streams, or raw bytes.
• Unified Parameter Conversions: Call the API using standard pythonic snake_case parameters which are automatically mapped to correct API payloads.
• Type Safety: Fully annotated with PEP-561 compliant types, allowing autocompletion in IDEs (VS Code, PyCharm).

---

📦 Installation

Install the package via pip (or from your private repository):

pip install vton-sdk

---

🔑 Quick Start

Set your API key as an environment variable or pass it directly to the client constructor:

export VTON_API_KEY="smd_live_..."

1. Synchronous Integration

from vton_sdk import VTONClient
from vton_sdk.exceptions import InsufficientCreditsError, AuthenticationError

# Initialize client (uses VTON_API_KEY env variable if not provided)
client = VTONClient()

try:
    # Upload images
    uploaded = client.upload_images(
        user_id="user_abc123",
        files=["person.jpg", "tshirt.png"]
    )
    urls = [asset['url'] for asset in uploaded]
    print(f"Uploaded URLs: {urls}")

    # Generate Try-on
    result = client.generate(
        platform="fal",
        model_name="quality",  # Deducts 1.0 credits
        input_image_urls=urls,
        prompt="Put the tshirt on the person",
        user_id="user_abc123"
    )

    if result.get("success"):
        print(f"Generated Try-on URL: {result['outputImageUrls'][0]}")

except AuthenticationError:
    print("Error: Invalid API Key")
except InsufficientCreditsError:
    print("Error: Insufficient credits. Please upgrade your plan.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

2. Asynchronous Integration

For high-performance async workflows:

import asyncio
from vton_sdk import AsyncVTONClient

async def main():
    client = AsyncVTONClient()
    
    # Check services availability
    health = await client.health_check()
    print("Health Status:", health["message"])

    # Asynchronous generation
    try:
        result = await client.generate(
            model_name="fast",
            input_clothes_image_urls=["https://example.com/clothes.jpg"],
            user_id="user_abc123"
        )
        print("Async Output:", result.get("outputImageUrls"))
    except Exception as e:
        print("Generation failed:", e)

if __name__ == "__main__":
    asyncio.run(main())

---

🛠️ API Reference

VTON Service

• health_check(): Verify availability.
• upload_images(user_id, files): Upload 1 to 4 images. Supports path strings, Path objects, bytes, or file-like objects.
• generate(...): Trigger VTON.
  • model_name: "fast", "medium", or "quality"
  • input_clothes_image_urls (or input_image_urls)
  • input_person_image_urls (optional)
  • prompt (optional)
  • platform: "fal", "replicate", or "gemini" (default: "fal")
  • version: 1.0 or 1.1 (default: 1.0)

API Key Management

• generate_api_key(user_id, label): Generate a new api key.
• list_api_keys(user_id): List all keys owned by user.
• revoke_api_key(key_id, user_id): Revoke a key.

User & Credit Management

• register_user(...): Register a new user & allocate free credits.
• check_user_credits(user_id): Retrieve credit balance.
• get_profile_details(user_id, method="POST"): Retrieve profile information.
• update_profile(user_id, name=None, company_name=None, phone_number=None, method="POST"): Update user profile.
• delete_account(user_id, method="POST"): Wipe user data and account.

Subscription Management

• get_subscription_status(user_id): Get subscription tiers and status details.

---

⚠️ Error Handling

The SDK maps standard HTTP errors to pythonic exceptions:

Exception	HTTP Status Code	Description
AuthenticationError	401	Missing, incorrect, or revoked X-API-Key
UnauthorizedError	403	User ID does not match the API Key owner
UserNotFoundError	404	Specified userId does not exist
APIKeyNotFoundError	404	Key reference query failed
InsufficientCreditsError	501	Credit balance is lower than the model credit cost
APIError	any other	Non-2xx API error

---

📄 License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.