API Reference

Complete documentation for all Dupify API endpoints. All endpoints accept JSON and return JSON. All image endpoints support batch processing for improved throughput.

Base URL: https://www.dupifyapp.com/v1

POST/v1/embed

Generate CLIP Embedding

Generate a 768-dimensional CLIP embedding vector for an image. Use these vectors for visual similarity search by calculating cosine similarity between embeddings.

Batch SupportQuality Score

Request Body

Parameter	Type	Description
image_url	string	URL of the image to process
image_base64	string	Base64-encoded image (alternative to URL)
images	array	Array of images for batch processing (max 10)
include_quality	boolean	Include image quality score (default: false)

Single Image Request

curl -X POST https://www.dupifyapp.com/v1/embed \
  -H "X-API-Key: fe_live_xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/product.jpg", "include_quality": true}'

Response with Quality Score

{
  "embedding": [0.023, -0.156, 0.089, 0.234, ...],
  "dimensions": 768,
  "processing_time_ms": 87,
  "quality": {
    "overall": 0.85,
    "sharpness": 0.92,
    "brightness": 0.78,
    "composition": 0.85
  }
}

Batch Request

curl -X POST https://www.dupifyapp.com/v1/embed \
  -H "X-API-Key: fe_live_xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      {"image_url": "https://example.com/product1.jpg"},
      {"image_url": "https://example.com/product2.jpg"}
    ]
  }'

Batch Response

{
  "results": [
    {"embedding": [...], "dimensions": 768, "cached": false},
    {"embedding": [...], "dimensions": 768, "cached": true}
  ],
  "processing_time_ms": 156
}

Responses are cached for 24 hours. Cached responses don't count against your quota.

POST/v1/background-remove

Remove Background

Remove the background from one or more images, returning transparent PNGs. Uses U2-Net model for high-quality segmentation.

Batch Support

Request Body

Parameter	Type	Description
image_url	string	URL of the image to process
image_base64	string	Base64-encoded image (alternative to URL)
images	array	Array of images for batch processing (max 10)
output_format	string	"png" or "webp" (default: png)

Example Request

curl -X POST https://www.dupifyapp.com/v1/background-remove \
  -H "X-API-Key: fe_live_xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/product.jpg"}'

Example Response

{
  "image_base64": "data:image/png;base64,iVBORw0KGgo...",
  "original_size": {"width": 800, "height": 600},
  "processing_time_ms": 1234
}

POST/v1/colors

Extract Dominant Colors

Extract dominant colors from an image with perceptual weighting. Returns hex codes sorted by visual prominence.

Batch Support

Request Body

Parameter	Type	Description
image_url	string	URL of the image to process
images	array	Array of images for batch processing (max 10)
num_colors	integer	Number of colors to extract (1-10, default: 5)

Example Request

curl -X POST https://www.dupifyapp.com/v1/colors \
  -H "X-API-Key: fe_live_xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/product.jpg", "num_colors": 5}'

Example Response

{
  "colors": [
    {"hex": "#E53935", "rgb": [229, 57, 53], "weight": 0.35},
    {"hex": "#FFFFFF", "rgb": [255, 255, 255], "weight": 0.25},
    {"hex": "#212121", "rgb": [33, 33, 33], "weight": 0.20},
    {"hex": "#FFCDD2", "rgb": [255, 205, 210], "weight": 0.12},
    {"hex": "#B71C1C", "rgb": [183, 28, 28], "weight": 0.08}
  ],
  "color_profile": "warm",
  "cached": false
}

POST/v1/silhouette

Generate Silhouette Embedding

Generate a shape-based embedding by first removing the background, then extracting the silhouette. Ideal for matching products by form regardless of color or pattern.

Batch Support

Request Body

Parameter	Type	Description
image_url	string	URL of the image to process
images	array	Array of images for batch processing (max 10)

Example Request

curl -X POST https://www.dupifyapp.com/v1/silhouette \
  -H "X-API-Key: fe_live_xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/dress.jpg"}'

Example Response

{
  "embedding": [0.012, 0.089, -0.045, ...],
  "dimensions": 256,
  "aspect_ratio": 0.75,
  "coverage": 0.65,
  "processing_time_ms": 234
}

Silhouette extraction includes automatic background removal, which adds processing time.

POST/v1/attributes

Detect Product Attributes

Automatically detect product attributes including category, style, material, and more from product title and description.

Batch Support

Request Body

Parameter	Type	Description
title	string	Product title (required)
description	string	Product description (optional)
category_hint	string	Category hint for better accuracy
items	array	Array of items for batch processing (max 20)

Example Request

curl -X POST https://www.dupifyapp.com/v1/attributes \
  -H "X-API-Key: fe_live_xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Women'''s Cotton V-Neck T-Shirt"}'

Example Response

{
  "category": "fashion",
  "garment_type": "shirt",
  "fabric": "cotton",
  "neckline": "v-neck",
  "confidence": 0.92,
  "cached": false
}

POST/v1/quality

Image Quality Score

Analyze image quality based on CLIP embedding statistics. Returns scores for overall quality, sharpness, brightness, and composition.

Batch Support

Request Body

Parameter	Type	Description
image_url	string	URL of the image to analyze
image_base64	string	Base64-encoded image (alternative to URL)
images	array	Array of images for batch processing (max 10)

Example Request

curl -X POST https://www.dupifyapp.com/v1/quality \
  -H "X-API-Key: fe_live_xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/product.jpg"}'

Example Response

{
  "quality": {
    "overall": 0.85,
    "sharpness": 0.92,
    "brightness": 0.78,
    "composition": 0.85
  },
  "processing_time_ms": 187
}

Quality scoring is also available as an option on the embed endpoint via include_quality: true.

POST/v1/similarity

Compare Images

Compare two images and get a cosine similarity score. Accepts image URLs, base64 data, or pre-computed embeddings.

Batch Support

Request Body

Parameter	Type	Description
image_url_1	string	URL of the first image
image_url_2	string	URL of the second image
embedding_1	number[]	Pre-computed embedding (skip image processing)
embedding_2	number[]	Pre-computed embedding (skip image processing)
pairs	array	Array of pairs for batch comparison (max 10)

Example Request

curl -X POST https://www.dupifyapp.com/v1/similarity \
  -H "X-API-Key: fe_live_xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "image_url_1": "https://example.com/product-a.jpg",
    "image_url_2": "https://example.com/product-b.jpg"
  }'

Example Response

{
  "similarity": 0.87,
  "match_level": "high",
  "processing_time_ms": 350
}

Match levels: high (≥ 0.85), medium (≥ 0.70), low (≥ 0.50), none (< 0.50). Pass pre-computed embeddings to skip image processing and reduce latency.

POST/v1/batch

Batch Processing

Run multiple operations on multiple images in a single request. Combine embedding, colors, silhouette, background removal, and quality scoring.

Request Body

Parameter	Type	Description
images	array	Array of images to process (max 10)
operations	string[]	Operations to run: embed, colors, silhouette, background-remove, quality

Example Request

curl -X POST https://www.dupifyapp.com/v1/batch \
  -H "X-API-Key: fe_live_xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      {"image_url": "https://example.com/product1.jpg"},
      {"image_url": "https://example.com/product2.jpg"}
    ],
    "operations": ["embed", "colors"]
  }'

Example Response

{
  "results": [
    {
      "image_url": "https://example.com/product1.jpg",
      "status": "success",
      "embed": {"embedding": [0.023, -0.156, ...], "dimensions": 768},
      "colors": {"colors": [...], "color_profile": "warm"}
    },
    {
      "image_url": "https://example.com/product2.jpg",
      "status": "success",
      "embed": {"embedding": [0.045, -0.089, ...], "dimensions": 768},
      "colors": {"colors": [...], "color_profile": "cool"}
    }
  ],
  "processing_time_ms": 460
}

Each image × operation counts as one API call for billing purposes. Operations run in parallel for maximum throughput.

Catalog API

Upload your own product catalog and search by visual similarity. See Catalog Docs for tier limits and advanced usage.

POST/v1/catalog/products

Upload Products

Upload a single product or a batch of products to your catalog. Products are automatically processed for CLIP embeddings, color extraction, and attribute detection.

Batch SupportAuto-Embedding

Request Body (Single Product)

Parameter	Type	Description
title	string	Product title (required)
image_url	string	Product image URL (required)
external_id	string	Your product ID for upsert matching
sku	string	Product SKU
description	string	Product description
brand	string	Brand name
category	string	Product category
price	number	Price amount
currency	string	Currency code (default: USD)
product_url	string	Product page URL
metadata	object	Custom key-value metadata

Single Product Upload

curl -X POST https://www.dupifyapp.com/v1/catalog/products \
  -H "X-API-Key: fe_live_xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Classic Leather Jacket",
    "image_url": "https://example.com/jacket.jpg",
    "external_id": "SKU-12345",
    "brand": "Acme",
    "category": "outerwear",
    "price": 299.99
  }'

Single Product Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "external_id": "SKU-12345",
  "sku": null,
  "status": "created",
  "embedding_status": "processing"
}

Batch Upload

curl -X POST https://www.dupifyapp.com/v1/catalog/products \
  -H "X-API-Key: fe_live_xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {"title": "Red Dress", "image_url": "https://example.com/red-dress.jpg"},
      {"title": "Blue Shirt", "image_url": "https://example.com/blue-shirt.jpg"}
    ],
    "generate_embeddings": true
  }'

Batch Response

{
  "products": [
    {"id": "...", "status": "created", "embedding_status": "processing"},
    {"id": "...", "status": "created", "embedding_status": "processing"}
  ],
  "total_created": 2,
  "total_updated": 0,
  "total_failed": 0
}

If external_id matches an existing product, it will be updated (upsert). Embeddings are generated asynchronously after upload.

GET/v1/catalog/products

List Products

List products in your catalog with filtering and pagination.

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Products per page (default: 20, max: 100)
embedding_status	string	Filter: pending, processing, completed, failed
category	string	Filter by category
search	string	Search in title and description

Example Request

curl https://www.dupifyapp.com/v1/catalog/products?page=1&per_page=10&category=outerwear \
  -H "X-API-Key: fe_live_xxxxx..."

Example Response

{
  "products": [
    {
      "id": "550e8400-...",
      "external_id": "SKU-12345",
      "title": "Classic Leather Jacket",
      "brand": "Acme",
      "category": "outerwear",
      "price": 299.99,
      "image_url": "https://example.com/jacket.jpg",
      "embedding_status": "completed"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 142,
    "total_pages": 15
  }
}

GET/v1/catalog/products/:id

Get Product

Retrieve a single product by its ID, including embedding status and extracted features.

Example Request

curl https://www.dupifyapp.com/v1/catalog/products/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: fe_live_xxxxx..."

Example Response

{
  "id": "550e8400-...",
  "external_id": "SKU-12345",
  "title": "Classic Leather Jacket",
  "brand": "Acme",
  "category": "outerwear",
  "price": 299.99,
  "image_url": "https://example.com/jacket.jpg",
  "embedding_status": "completed",
  "embedding_generated_at": "2025-01-15T10:30:00Z",
  "dominant_colors": [
    {"hex": "#2D1B0E", "rgb": [45, 27, 14], "weight": 0.45},
    {"hex": "#5C3A1E", "rgb": [92, 58, 30], "weight": 0.30}
  ],
  "color_profile": "warm"
}

DELETE/v1/catalog/products/:id

Delete Product

Permanently delete a product from your catalog.

Example Request

curl -X DELETE https://www.dupifyapp.com/v1/catalog/products/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: fe_live_xxxxx..."

Example Response

{
  "success": true,
  "deleted": true
}

POST/v1/catalog/search

Search Catalog by Image

Search your product catalog using visual similarity. Provide an image URL, base64 image, existing product ID, or a pre-computed CLIP embedding.

Request Body

Parameter	Type	Description
image_url	string	Image URL to search with
image_base64	string	Base64 image to search with
product_id	string	Find products similar to this catalog product
embedding	number[]	Pre-computed 768-dim CLIP embedding
max_results	integer	Maximum results (default: 20)
similarity_threshold	number	Minimum similarity score 0-1 (default: 0.70)
category	string	Filter results by category
min_price	number	Minimum price filter
max_price	number	Maximum price filter

Example Request

curl -X POST https://www.dupifyapp.com/v1/catalog/search \
  -H "X-API-Key: fe_live_xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/query-image.jpg",
    "max_results": 10,
    "similarity_threshold": 0.75
  }'

Example Response

{
  "results": [
    {
      "id": "550e8400-...",
      "title": "Classic Leather Jacket",
      "brand": "Acme",
      "price": 299.99,
      "image_url": "https://example.com/jacket.jpg",
      "similarity_score": 0.92
    },
    {
      "id": "660f9511-...",
      "title": "Vintage Biker Jacket",
      "brand": "Heritage",
      "price": 249.99,
      "image_url": "https://example.com/biker.jpg",
      "similarity_score": 0.87
    }
  ],
  "query": {"type": "image"},
  "total_found": 2,
  "processing_time_ms": 312
}

One of image_url, image_base64, product_id, or embedding is required. Catalog searches count toward your monthly API call limit.

← Authentication Rate Limits →