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

fromvton_sdkimportVTONClientfromvton_sdk.exceptionsimportInsufficientCreditsError, AuthenticationError# Initialize client (uses VTON_API_KEY env variable if not provided)client=VTONClient()
try:
# Upload imagesuploaded=client.upload_images(
user_id="user_abc123",
files=["person.jpg", "tshirt.png"]
)
urls= [asset['url'] forassetinuploaded]
print(f"Uploaded URLs: {urls}")
# Generate Try-onresult=client.generate(
platform="fal",
model_name="quality", # Deducts 1.0 creditsinput_image_urls=urls,
prompt="Put the tshirt on the person",
user_id="user_abc123"
)
ifresult.get("success"):
print(f"Generated Try-on URL: {result['outputImageUrls'][0]}")
exceptAuthenticationError:
print("Error: Invalid API Key")
exceptInsufficientCreditsError:
print("Error: Insufficient credits. Please upgrade your plan.")
exceptExceptionase:
print(f"An unexpected error occurred: {e}")

2. Asynchronous Integration

For high-performance async workflows:

importasynciofromvton_sdkimportAsyncVTONClientasyncdefmain():
client=AsyncVTONClient()
# Check services availabilityhealth=awaitclient.health_check()
print("Health Status:", health["message"])
# Asynchronous generationtry:
result=awaitclient.generate(
model_name="fast",
input_clothes_image_urls=["https://example.com/clothes.jpg"],
user_id="user_abc123"
)
print("Async Output:", result.get("outputImageUrls"))
exceptExceptionase:
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.