Skip to content

Latest commit

 

History

History
584 lines (481 loc) · 17.4 KB

API.md

File metadata and controls

584 lines (481 loc) · 17.4 KB

Snapmydesign (SMD) SDK API Reference

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.


📌 Base URLs

Environment Base URL
Production https://apisdk.snapmydesign.com/api/v1
Local Development http://localhost:8000/api/v1

🔐 Authentication

The backend supports two authentication mechanisms depending on the API endpoint category:

1. SDK API Key Authentication (X-API-Key)

  • 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 userId and check active credit balance.

2. User & Subscription Management Authentication

  • Endpoints like user registration, profile updates, and subscription status check do not require the X-API-Key header.
  • These endpoints are designed to accept the userId in 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.

🗺️ Architectural Flows

Request Lifecycle and API Key Verification

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
Loading

🛠️ API Endpoint Reference

1. VTON (Virtual Try-On) Service

📤 Upload VTON Images

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
Request Parameters
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.
Response (UploadResponse)
{
  "success": true,
  "uploaded": [
    {
      "id": "e4a2d8b5-908c-4a34-be57-410a0e954a1a",
      "url": "https://firebasestorage.googleapis.com/.../vton_uploaded_image..."
    }
  ],
  "statusCode": 200,
  "message": "Upload successful"
}

🪄 Generate Try-On

Trigger the virtual try-on generation process.

  • Method: POST
  • Path: /vton/generate
  • Authentication Required: Yes (X-API-Key)
  • Content-Type: application/json
Request Body (VTONRequest)
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)
Response (VTONResponse)
{
  "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.").


🔍 VTON Health Check

Verify the availability of the VTON services.

  • Method: GET
  • Path: /vton
  • Authentication Required: No
Response
{
  "status": 200,
  "message": "success",
  "mode": "vton service from SMD SDK",
  "data": []
}

2. API Key Management

🔑 Generate API Key

Create a new API key for developer integrations.

  • Method: POST
  • Path: /apikey/generate
  • Authentication Required: No (Accepts userId in payload)
  • Content-Type: application/json
Request Body (ApiKeyCreate)
{
  "userId": "user_abc123",
  "label": "my-production-key"
}
Response (ApiKeyCreated)
{
  "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.


📋 List API Keys

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.
Response (List[ApiKeySummary])
[
  {
    "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
  }
]

❌ Revoke API Key

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.
Response
{
  "success": true,
  "message": "API key revoked successfully"
}

3. User & Credits Management

📝 Register User

Registers a new user in the SDK Firestore system and allocates initial free credits.

  • Method: POST
  • Path: /user/register
  • Content-Type: application/json
Request Body (User)
{
  "emailId": "developer@example.com",
  "name": "Jane Doe",
  "profileUrl": "",
  "timestamp": "2026-05-28T12:00:00Z",
  "userId": "user_abc123",
  "companyName": "Tech Corp",
  "phoneNumber": "+1234567890"
}
Response (UserResponse)
{
  "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).


🪙 Check User Credits

Fetch the remaining credit balance for a user.

  • Method: POST
  • Path: /user/credits
  • Content-Type: application/json
Request Body (UserCreditsRequest)
{
  "userId": "user_abc123"
}
Response (UserCreditsResponse)
{
  "success": true,
  "message": "User credits found",
  "credits": {
    "user": {
      "userId": "user_abc123"
    },
    "credits": 42.5
  },
  "statusCode": 200
}

👤 Get Profile Details

Fetch detailed profile and metadata for a user (including credits and subscription status). Supported on both GET and POST methods.

  • Method: GET (Query parameter) or POST (Body payload)
  • Path: /user/profile-details
Request Body (ProfileDetailsRequest - POST only)
{
  "userId": "user_abc123"
}
Response (ProfileDetailsResponse)
{
  "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 Profile Details (Unified)

Update name, company name, and phone number simultaneously. Supported on both PUT and POST methods.

  • Method: PUT or POST
  • Path: /user/profile
  • Content-Type: application/json
Request Body (UnifiedProfileUpdateRequest)
{
  "userId": "user_abc123",
  "name": "Jane R. Doe",
  "companyName": "Acme Inc.",
  "phoneNumber": "+1987654321"
}
Response (UnifiedProfileUpdateResponse)
{
  "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 User Account

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: DELETE or POST
  • Path: /user/account (for DELETE) or /user/delete-account (for POST)
  • Content-Type: application/json
Request Body (DeleteAccountRequest)
{
  "userId": "user_abc123"
}
Response (DeleteAccountResponse)
{
  "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"
    ]
  }
}

4. Subscription Management

💳 Get Subscription Status

Check subscription tiers, validity, and timestamps.

  • Method: POST
  • Path: /subscription/status
  • Content-Type: application/json
Request Body (SubscriptionRequest)
{
  "userId": "user_abc123"
}
Response (SubscriptionResponse)
{
  "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 Model & Credit Cost Matrix

VTON execution credit cost is determined by the selected version and model name (VTONRequest.model_name).

Pricing & Platform Map

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

💳 Subscriptions & Top-ups Matrix

The platform offers duration-based subscriptions and credit top-ups processed via Dodo Payments.

Duration Plans

  • 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

Credit Top-ups (One-Time, Do Not Expire)

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

⚠️ Error Codes & Custom Exceptions

The application maps specific errors directly to standardized HTTP status codes.

Subscription status codes

  • 101: SUBSCRIPTION_FREE_CODE
  • 102: SUBSCRIPTION_PRO_CODE (Monthly)
  • 103: SUBSCRIPTION_PLUS_CODE (Monthly)
  • 104: SUBSCRIPTION_ENTERPRISE_CODE (Monthly)
  • 402 / 403 / 404: 4-Month Pro / Plus / Enterprise Subscription Codes
  • 1202 / 1203 / 1204: 12-Month Pro / Plus / Enterprise Subscription Codes

Application Exceptions (AppException)

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.

🐍 Python SDK Integration Example

External clients can easily invoke the API using the official vton-sdk library.

Basic Workflow

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)}")