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>.

Google
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.

Request
{
  "imageUrls": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ]
}
Response
{
  "success": true,
  "data": {
    "_id": "product_id",
    "productName": "Product Name",
    "aiAnalysis": { ... },
    "colors": ["black", "white", "red"],
    "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": ["black", "white", "red"]
  }
}
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/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
vto Virtual Try-On images (requires VTO setup) 1:1, 4:3, 3:4, 16:9, 9:16