EcomViz API Documentation

Use our REST API to integrate EcomViz's powerful image generation capabilities into your applications.

API Token Management

Manage your API access credentials

Use this token to authenticate your API requests. Include it in the Authorization header as Bearer <your-token>.

Authentication

Secure your API requests

All API endpoints require authentication. Include your API token in the Authorization header:

{Authorization: Bearer YOUR_API_TOKEN}

API Endpoints

Organized by category

POST

/api/products/url

Create a new product by providing image URLs for AI analysis. Optionally, include additional product information to guide the AI analysis and improve accuracy.

Request

{
  "imageUrls": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "productsInfo": "Optional additional information about the product to guide AI analysis (e.g., brand, material, intended use, etc.)"
}

Response

{
  "success": true,
  "data": {
    "_id": "product_id",
    "productName": "Product Name",
    "aiAnalysis": { ... },
    "colors": [{"name": "Black", "code": "#000000"}, {"name": "White", "code": "#ffffff"}],
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

GET

/api/products/:productId

Retrieve product details including generated images and AI analysis.

Response

{
  "success": true,
  "data": {
    "_id": "product_id",
    "productName": "Product Name",
    "generatedImages": [
      {
        "filePath": "path/to/image.jpg",
        "generatedAt": "2024-01-01T00:00:00.000Z",
        "generationParams": {
          "platform": "general",
          "region": "global",
          "imageType": "main",
          "color": "red"
        }
      }
    ],
    "aiAnalysis": { ... },
    "colors": [{"name": "Black", "code": "#000000"}, {"name": "White", "code": "#ffffff"}]
  }
}

POST

/api/products/:productId/generate

Generate AI images for a product. This is an asynchronous operation. Results will be sent to your webhook URL.

Request

{
  "imageType": [
    { "main": 3, "aspectRatio": "1:1" },
    { "detail": 2, "aspectRatio": "4:3" },
    { "vto": ["red", "blue"] }
  ],
  "region": "global",
  "platform": "general",
  "removeBrandLogo": false,
  "changePortrait": false,
  "language": "org_text",
  "webhook": {
    "url": "https://your-server.com/webhook",
    "token": "optional-verification-token"
  }
}

Response

{
  "success": true,
  "message": "Image generation task started",
  "productId": "product_id"
}

Webhook Notification

When image generation completes, a POST request will be sent to your webhook URL:

{
  "productId": "product_id",
  "status": "completed",
  "generatedImages": [...]
}

POST

/api/products/:productId/generate-color-images

Generate spec images for each product color using a General Template (PreSuggestion). One image is generated per color. This is an asynchronous operation — images appear in the Product Spec Images tab when complete, and the URL is automatically pushed to colors[].url.

Request

{
  "preSuggestionId": "69a92e8709eec30bbd7f030b",
  "colors": [
    { "name": "Black" },
    { "name": "White" }
  ],
  "aspectRatio": "1:1",
  "removeBrandLogo": false,
  "changePortrait": false,
  "language": "org_text"
}

Request Fields

Field	Type	Required	Description
`preSuggestionId`	string	Yes	The General Template ID to use for generation
`colors`	array	No	Colors to generate for. Each item: `{ "name": "colorName" }`. If omitted, generates for all product colors.
`aspectRatio`	string	No	Default: `"1:1"`. Options: "1:1", "3:2", "2:3", "16:9", "9:16", "21:9", "9:21"
`removeBrandLogo`	boolean	No	Default: `false`
`changePortrait`	boolean	No	Default: `false`
`language`	string	No	Default: `"org_text"`. Text language for generated images.

Response

{
  "success": true,
  "message": "Color spec image generation started",
  "productId": "product_id",
  "colors": [
    { "name": "Black", "code": "#000000" },
    { "name": "White", "code": "#ffffff" }
  ],
  "preSuggestionId": "69a92e8709eec30bbd7f030b",
  "imageType": "spec"
}

GET

/api/products/:productId/colors

Get product colors with their image URLs, generated spec images, and primary index settings.

Response

{
  "success": true,
  "colors": [
    {
      "name": "Black",
      "code": "#000000",
      "url": [
        "https://cdn.example.com/spec_black_1.jpg",
        "https://cdn.example.com/spec_black_2.jpg"
      ],
      "primaryIndex": 0,
      "generatedImages": [
        {
          "fileName": "spec_black_1.jpg",
          "filePath": "https://cdn.example.com/spec_black_1.jpg",
          "generatedAt": "2024-01-01T00:00:00.000Z"
        }
      ]
    }
  ],
  "productName": "Product Name"
}

PUT

/api/products/:productId/colors/primary

Set which image in a color's url[] array is the primary/thumbnail image. The primaryIndex controls which image is shown as the color's representative thumbnail in the Spec Images tab and other UIs.

Request

{
  "colorName": "Black",
  "primaryIndex": 1
}

Response

{
  "success": true,
  "colorName": "Black",
  "primaryIndex": 1,
  "urlLength": 3
}

Publishing requirements

Before publishing, the merchant store must be configured in VtoMirror with store name, slug, URL, icon, supported languages, and shipping regions. The product must also have a VTO category, colors, VTO model data, a display image, and a VTO image.

Authorization: Bearer YOUR_API_TOKEN

GET

/api/products/vto-mirror/published

List products published to the VtoMirror storefront for the authenticated token owner. Results are sorted by vtoMirror.sortOrder descending, then vtoMirror.publishedAt descending, then createdAt descending.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number, minimum 1.
`limit`	integer	20	Products per page, minimum 1, maximum 100.

Response

{
  "success": true,
  "products": [
    {
      "_id": "product_id",
      "productName": "Product Name",
      "vtoMirror": {
        "isPublished": true,
        "title": "Storefront title",
        "sortOrder": 10,
        "prices": [{ "currency": "HKD", "price": 299 }]
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 126,
    "totalPages": 7,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

GET

/api/products/:productId/vto-mirror/publish-defaults

Get publish readiness and merchant defaults for a product. Product images are selected automatically from the product's own first available display and VTO candidates.

Response

{
  "success": true,
  "merchantSetupComplete": true,
  "merchantProfile": {
    "storeName": "Demo Store",
    "storeSlug": "demo-store",
    "storeUrl": "https://store.example.com",
    "supportedLanguages": ["en-US", "zh-TW"],
    "shippingRegions": ["HK", "US"],
    "primaryCurrency": "HKD"
  },
  "publishStatus": {
    "canPublish": true,
    "reasons": []
  }
}

POST

/api/products/:productId/vto-mirror/publish

Publish or update a product on VtoMirror. If supportedLanguages or salesRegions is omitted, the API uses the merchant store defaults. Product images are selected automatically from the product's own first available display and VTO candidates.

Request

{
  "title": "Storefront product title",
  "productUrl": "https://store.example.com/products/sku-123",
  "prices": [
    { "currency": "HKD", "price": 299 },
    { "currency": "USD", "price": 39 }
  ],
  "sortOrder": 10
}

Request Fields

Field	Type	Required	Description
`title`	string	Yes	Storefront product title
`prices`	array	Yes	Price list. Must include the merchant primary currency.
`productUrl`	string	Yes	External product URL.
`supportedLanguages`	array/string	No	Defaults to merchant store supported languages.
`salesRegions`	array/string	No	Defaults to merchant store shipping regions.
`sortOrder`	integer	No	Higher values can be used for storefront ordering.

Response

{
  "success": true,
  "product": {
    "_id": "product_id",
    "productName": "Product Name",
    "vtoMirror": {
      "isPublished": true,
      "title": "Storefront product title",
      "supportedLanguages": ["en-US", "zh-TW"],
      "salesRegions": ["HK", "US"],
      "prices": [{ "currency": "HKD", "price": 299 }]
    },
    "publishStatus": {
      "canPublish": true,
      "reasons": []
    }
  }
}

Common Errors

{
  "success": false,
  "error": "Please complete your VTO Mirror merchant profile first",
  "requiresMerchantSetup": true,
  "redirectUrl": "/vto-mirror"
}

{
  "success": false,
  "error": "This product is not ready to publish to VTO Mirror",
  "reasons": ["missingVtoImage"]
}

POST

/api/products/:productId/vto-mirror/unpublish

Unpublish a product from VtoMirror while keeping its existing VtoMirror metadata for future reuse.

Response

{
  "success": true,
  "product": {
    "_id": "product_id",
    "productName": "Product Name",
    "vtoMirror": {
      "isPublished": false,
      "unpublishedAt": "2026-06-15T00:00:00.000Z"
    }
  }
}

POST

/api/vto/generate-url

Generate virtual try-on images by providing image URLs.

Headers

Authorization: Bearer YOUR_API_TOKEN

Request

{
  "personImageUrl": "https://example.com/person.jpg",
  "clothingImageUrls": [
    {"url": "https://example.com/clothing1.jpg", "info": "price US9.9"},
    {"url": "https://example.com/clothing2.jpg", "info": "price US7.9, only for kids"}
  ],
  "height": 170,         // Optional, range: [50, 250], unit: cm
  "weight": 60,          // Optional, range: [10, 300], unit: kg
  "aspectRatio": "2:3",  // Optional, default: "2:3", options: ["1:1", "3:2", "2:3", "16:9", "9:16", "21:9", "9:21"]
  "watermark": true,     // Optional, default: true, set to false to disable watermark
  "webhook": {           // Optional
    "url": "https://your-server.com/webhook",
    "token": "optional_secret_token"
  }
}

Response

{
  "success": true,
  "message": "VTO try-on image generation task has been submitted",
  "vtoId": "vto_id",
  "personImage": "https://example.com/person.jpg",
  "clothingImages": ["https://example.com/clothing1.jpg"]
}

GET

/api/vto/:vtoId

Get VTO task result by task ID.

Headers

Authorization: Bearer YOUR_API_TOKEN

Response

{
  "success": true,
  "data": {
    "_id": "vto_id",
    "status": "completed",
    "personImage": { "filePath": "https://example.com/person.jpg" },
    "clothingImages": [{ "filePath": "https://example.com/clothing1.jpg" }],
    "generatedImages": [
      { "filePath": "https://example.com/generated1.jpg" }
    ],
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:05:00.000Z"
  }
}

Webhook

Webhook Notification

When the VTO task is completed, a POST request will be sent to your webhook URL.

Webhook Payload

{
  "vtoId": vtoId,
  "status": "completed",
  "generatedImages": [
    { "filePath": "https://example.com/generated1.jpg" }
  ],
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:05:00.000Z"
}

Image Type Reference

Supported image generation types

Type	Description	Recommended Aspect Ratio
`main`	Main product images for listings	1:1, 4:3, 3:4, 16:9, 9:16
`detail`	Detailed product feature images	1:1, 4:3, 3:4, 16:9, 9:16
`facebook`	Facebook optimized images	1:1, 4:3, 3:4, 16:9, 9:16
`spec`	Product spec/color-variant images generated via General Templates	1:1, 4:3, 3:4, 16:9, 9:16
`vto`	Virtual Try-On images (requires VTO setup)	1:1, 4:3, 3:4, 16:9, 9:16