Welcome to the Snapmydesign (SMD) SDK API Reference. This documentation details the REST API endpoints, schemas, authentication methods, and business logic for the Virtual Try-On (VTON) SDK Backend service.
| Environment | Base URL |
|---|---|
| Production | https://apisdk.snapmydesign.com/api/v1 |
| Local Development | http://localhost:8000/api/v1 |
The backend supports two authentication mechanisms depending on the API endpoint category:
- Used for programmatic, external client integrations (e.g. VTON generation and uploads).
- Provided as a custom header:
X-API-Key: smd_live_... - All requests utilizing this header are validated to resolve the active
userIdand check active credit balance.
- Endpoints like user registration, profile updates, and subscription status check do not require the
X-API-Keyheader. - These endpoints are designed to accept the
userIdin the request body directly. - Behind the scenes, Firebase ID tokens can also be validated using the
Authorization: Bearer <Firebase_ID_Token>header for protected administrative/client actions.
sequenceDiagram
autonumber
Client->{API Router}: POST /vton/generate (Headers: X-API-Key, Body: VTONRequest)
API Router->{Auth Dependency}: require_api_key(x_api_key)
Auth Dependency->{Firestore}: Lookup & verify API Key
alt Key Invalid or Revoked
Firestore-->>Auth Dependency: Key not found / revoked
Auth Dependency-->>Client: HTTP 401 Unauthorized (Invalid API Key)
else Key Valid
Firestore-->>Auth Dependency: Returns key_data (userId, label, status)
Auth Dependency-->>API Router: Returns authenticated userId
end
API Router->{API Router}: Enforce userId matches key owner
API Router->{VTON Service}: Execute generate(request)
VTON Service->{Firestore}: Check user credits
alt Insufficient Credits
VTON Service-->>Client: HTTP 405 / 501 Insufficient Credits
else Credits Sufficient
VTON Service->{Third-Party AI}: Call model (FAL / Replicate)
Third-Party AI-->>VTON Service: Returns generated image URL
VTON Service->{Cloud Storage}: Upload image to user directory
VTON Service->{Firestore}: Deduct credits & log generation
VTON Service-->>Client: Return VTONResponse (HTTP 200)
end
Upload images (person/garments) to the cloud storage bucket to obtain public URLs required for the try-on generation.
- Method:
POST - Path:
/vton/upload - Authentication Required: Yes (
X-API-Key) - Content-Type:
multipart/form-data
| Name | Type | Location | Description |
|---|---|---|---|
files |
List[File] |
Form Data | 1 to 4 image files to upload. |
userId |
string |
Form Data | Must match the userId associated with the X-API-Key. |
{
"success": true,
"uploaded": [
{
"id": "e4a2d8b5-908c-4a34-be57-410a0e954a1a",
"url": "https://firebasestorage.googleapis.com/.../vton_uploaded_image..."
}
],
"statusCode": 200,
"message": "Upload successful"
}Trigger the virtual try-on generation process.
- Method:
POST - Path:
/vton/generate - Authentication Required: Yes (
X-API-Key) - Content-Type:
application/json
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
model_name |
string |
Yes | — | Options: "fast", "medium", "quality" |
inputClothesImageUrls |
List[string] |
Yes | — | List of 1 to 4 URLs (the clothes to try on) |
inputPersonImageUrls |
List[string] |
No | [] |
List of up to 4 reference model URLs |
prompt |
string |
No | "" |
Instruction description (e.g. "Replace the shirt with...") |
userId |
string |
No | "user_id" |
Will be overwritten with the authenticated API key's owner |
platform |
string |
No | "fal" |
Target AI platform: "fal", "replicate", "gemini" |
version |
float |
No | 1.0 |
Model version: 1.0 or 1.1 |
internal_testing |
boolean |
No | false |
If true, skips credit checks/deductions (Internal use) |
{
"success": true,
"outputImageUrls": [
"https://firebasestorage.googleapis.com/.../vton_generated_image..."
],
"generationId": "50c76d05-4f40-424a-9ef8-11db9390234a",
"inputClothesImageUrls": [
"https://firebasestorage.googleapis.com/.../vton_uploaded_image..."
],
"inputPersonImageUrls": [],
"userId": "user_abc123",
"statusCode": 200,
"creditCost": 0.5,
"modelName": "medium",
"message": "success",
"version": 1.0,
"prompt": "Replace the clothing in the first image with the garment from the 1th image."
}Tip
Prompt Auto-Generation: If prompt is left blank, the backend automatically generates a descriptive prompt based on the count of your clothing and model images (e.g. "Replace the clothing in the first image with the garment from the 2nd image.").
Verify the availability of the VTON services.
- Method:
GET - Path:
/vton - Authentication Required: No
{
"status": 200,
"message": "success",
"mode": "vton service from SMD SDK",
"data": []
}Create a new API key for developer integrations.
- Method:
POST - Path:
/apikey/generate - Authentication Required: No (Accepts
userIdin payload) - Content-Type:
application/json
{
"userId": "user_abc123",
"label": "my-production-key"
}{
"keyId": "key_7y2b78g...",
"userId": "user_abc123",
"apiKey": "smd_live_76fa2312b9...",
"label": "my-production-key",
"createdAt": "2026-05-28T12:00:00+05:30",
"message": "Store this key securely; it cannot be shown again."
}Warning
Key Security: The generated raw API key is returned only once upon creation. Store it immediately, as it is hashed before saving to Firestore and cannot be retrieved later.
Retrieve a summary of all API keys created by a specific user.
- Method:
GET - Path:
/apikey - Query Parameters:
userId(string, required): The ID of the user owning the keys.
[
{
"keyId": "key_7y2b78g...",
"userId": "user_abc123",
"keyPrefix": "smd_live_",
"apiKey": "smd_live_76fa...",
"label": "my-production-key",
"createdAt": "2026-05-28T12:00:00+05:30",
"revoked": false
}
]Permanently revoke and delete an API key, preventing any further requests using it.
- Method:
DELETE - Path:
/apikey/{key_id} - Query Parameters:
userId(string, required): The ID of the user owning the key.
{
"success": true,
"message": "API key revoked successfully"
}Registers a new user in the SDK Firestore system and allocates initial free credits.
- Method:
POST - Path:
/user/register - Content-Type:
application/json
{
"emailId": "developer@example.com",
"name": "Jane Doe",
"profileUrl": "",
"timestamp": "2026-05-28T12:00:00Z",
"userId": "user_abc123",
"companyName": "Tech Corp",
"phoneNumber": "+1234567890"
}{
"success": true,
"message": "User registered successfully",
"user": {
"emailId": "developer@example.com",
"name": "Jane Doe",
"profileUrl": "https://firebasestorage.googleapis.com/.../avatar_male.jpg",
"timestamp": "2026-05-28T12:00:00Z",
"userId": "user_abc123",
"companyName": "Tech Corp",
"phoneNumber": "+1234567890",
"registrationDate": "2026-05-28T12:00:00+05:30",
"lastSignIn": "2026-05-28T12:00:00+05:30",
"accountType": "Free User"
},
"statusCode": 200
}Note
Upon registration, the database allocates the default free credits defined in INITTIAL_USER_CREDIT (currently 2.0 credits).
Fetch the remaining credit balance for a user.
- Method:
POST - Path:
/user/credits - Content-Type:
application/json
{
"userId": "user_abc123"
}{
"success": true,
"message": "User credits found",
"credits": {
"user": {
"userId": "user_abc123"
},
"credits": 42.5
},
"statusCode": 200
}Fetch detailed profile and metadata for a user (including credits and subscription status). Supported on both GET and POST methods.
- Method:
GET(Query parameter) orPOST(Body payload) - Path:
/user/profile-details
{
"userId": "user_abc123"
}{
"success": true,
"message": "Profile details retrieved successfully",
"statusCode": 200,
"data": {
"userId": "user_abc123",
"emailId": "developer@example.com",
"name": "Jane Doe",
"profileUrl": "https://firebasestorage.googleapis.com/.../avatar_male.jpg",
"companyName": "Tech Corp",
"phoneNumber": "+1234567890",
"registrationDate": "2026-05-28T12:00:00+05:30",
"credits": 42.5,
"accountType": "Plus User",
"lastSignIn": "2026-05-28T12:15:00+05:30"
}
}Update name, company name, and phone number simultaneously. Supported on both PUT and POST methods.
- Method:
PUTorPOST - Path:
/user/profile - Content-Type:
application/json
{
"userId": "user_abc123",
"name": "Jane R. Doe",
"companyName": "Acme Inc.",
"phoneNumber": "+1987654321"
}{
"success": true,
"message": "Profile updated successfully",
"statusCode": 200,
"data": {
"userId": "user_abc123",
"name": "Jane R. Doe",
"companyName": "Acme Inc.",
"phoneNumber": "+1987654321",
"updatedAt": "2026-05-28T12:18:00.123456"
}
}Delete a user and wipe all documents across Firestore database collections associated with their userId (including gallery items, photoshoot uploads, tryon logs, orders, and Firebase Auth registration). Supported on both DELETE and POST methods.
- Method:
DELETEorPOST - Path:
/user/account(forDELETE) or/user/delete-account(forPOST) - Content-Type:
application/json
{
"userId": "user_abc123"
}{
"success": true,
"message": "Account deleted successfully",
"statusCode": 200,
"data": {
"userId": "user_abc123",
"deletedAt": "2026-05-28T12:19:00.123456",
"deletedCollections": [
"users (1 docs)",
"credits (1 docs)",
"tryon_generation (12 docs)",
"firebase_auth"
]
}
}Check subscription tiers, validity, and timestamps.
- Method:
POST - Path:
/subscription/status - Content-Type:
application/json
{
"userId": "user_abc123"
}{
"endingTimestamp": {
"seconds": 1782628800,
"nanoseconds": 0
},
"subscriptionId": "sub_92u1hbasn...",
"transactionId": "tx_23hbas7...",
"transactionTimestamp": {
"seconds": 1772155200,
"nanoseconds": 0
},
"type": "plus_monthly",
"userId": "user_abc123",
"message": "Subscription found",
"statusCode": 200,
"subscriptionCode": 103,
"previous_type": null,
"previous_subscriptionCode": null
}VTON execution credit cost is determined by the selected version and model name (VTONRequest.model_name).
| Version | Model Name (model_name) |
Target AI Platform | Back-end Model Used | Credit Cost |
|---|---|---|---|---|
| 1.0 (Default) | fast |
FAL | fal-ai/flux-2/klein/4b/edit |
0.25 |
| 1.0 (Default) | medium |
FAL | fal-ai/flux-2/klein/9b/edit |
0.50 |
| 1.0 (Default) | quality |
FAL | fal-ai/flux-2/klein/9b/edit |
1.00 |
| 1.1 | fast |
Replicate | black-forest-labs/flux-2-klein-4b |
0.25 |
| 1.1 | medium |
Replicate | black-forest-labs/flux-2-klein-9b |
0.50 |
| 1.1 | quality |
Replicate | prunaai/p-image-edit |
1.00 |
The platform offers duration-based subscriptions and credit top-ups processed via Dodo Payments.
- Plus Plan: Targeted for builders starting up.
- Pro Plan: Targeted for higher-volume deployments.
| Plan Key | Duration | USD Price | INR Price | Credits Allocated | Dodo Payment Checkout URL |
|---|---|---|---|---|---|
plus_monthly |
30 Days | $5 | ₹400 | 20.0 | Checkout Link |
pro_monthly |
30 Days | $10 | ₹800 | 40.0 | Checkout Link |
plus_4months |
120 Days | $17 | ₹1360 | 80.0 | Checkout Link |
pro_4months |
120 Days | $34 | ₹2720 | 160.0 | Checkout Link |
plus_yearly |
365 Days | $48 | ₹3840 | 240.0 | Checkout Link |
pro_yearly |
365 Days | $96 | ₹7680 | 480.0 | Checkout Link |
| Plan Key | Duration | USD Price | INR Price | Credits Allocated | Dodo Payment Checkout URL |
|---|---|---|---|---|---|
topup_monthly |
Lifetime | $10 | ₹800 | 40.0 | Checkout Link |
topup_4months |
Lifetime | $34 | ₹2720 | 160.0 | Checkout Link |
topup_yearly |
Lifetime | $96 | ₹7680 | 480.0 | Checkout Link |
The application maps specific errors directly to standardized HTTP status codes.
101:SUBSCRIPTION_FREE_CODE102:SUBSCRIPTION_PRO_CODE(Monthly)103:SUBSCRIPTION_PLUS_CODE(Monthly)104:SUBSCRIPTION_ENTERPRISE_CODE(Monthly)402/403/404: 4-Month Pro / Plus / Enterprise Subscription Codes1202/1203/1204: 12-Month Pro / Plus / Enterprise Subscription Codes
When an exception occurs within the services, the FastAPI app returns a structured JSON payload:
{"detail": "Error Message Content"}
| Custom Exception Class | HTTP Status | Description |
|---|---|---|
InvalidAPIKeyError |
401 |
Missing, incorrect, or revoked X-API-Key header. |
UnauthorizedError |
403 |
User ID specified in request does not match the key owner. |
UserNotFoundError |
404 |
Specified userId does not exist in the database. |
APIKeyNotFoundError |
404 |
Key reference query failed to find any record. |
InsufficientCreditsError |
501 |
Credit balance is lower than the model credit cost. |
External clients can easily invoke the API using the official vton-sdk library.
from vton_sdk import VTONClient
from vton_sdk.exceptions import InsufficientCreditsError, AuthenticationError
# 1. Initialize Client
client = VTONClient(
api_key="smd_live_76fa2312b9...",
base_url="https://apisdk.snapmydesign.com/api/v1"
)
try:
# 2. Upload model & garment images to storage
uploaded_assets = client.upload_images(
user_id="user_abc123",
files=["person.jpg", "tshirt.png"]
)
urls = [asset['url'] for asset in uploaded_assets]
print(f"Uploaded URLs: {urls}")
# 3. Request Try-on generation
result = client.generate(
platform="fal",
model_name="quality", # Deducts 1.0 credit
input_image_urls=urls,
prompt="Put the tshirt on the person",
user_id="user_abc123"
)
if result.get('success'):
print(f"Generated Tryon Image URL: {result['outputImageUrls'][0]}")
print(f"Generation ID: {result['generationId']}")
except AuthenticationError:
print("Failed: Invalid API Key")
except InsufficientCreditsError:
print("Failed: Insufficient credits. Please buy a top-up.")
except Exception as e:
print(f"Error occurred: {str(e)}")