PSMEDx API

Overview

PSMEDx (PromoStandards Media Extended) provides powerful image processing capabilities specifically designed for the promotional products industry. These APIs enable you to manipulate product images, extract colors, apply decorations, and perform advanced image analysis.

Key Capabilities

Background Removal - Remove backgrounds from product images
Product Decoration - Apply artwork to blank product images
Color Analysis - Extract dominant colors and find Pantone matches
Image Classification - Classify images as blank or decorated
Vectorization - Convert raster images to SVG vectors
Bounding Box Detection - Find decoration areas on products

Authentication

All PSMEDx endpoints require authentication.

X-API-Key: your-api-key-here

Or:

Authorization: Bearer your-token-here

Base URL

https://api.psrestful.com/psmedx/v1

Image Processing APIs

Remove Background

Remove the background from a product image, returning a transparent PNG.

Endpoint:

GET /psmedx/v1/remove-background/

Query Parameters:

Parameter	Type	Default	Description
`image_url`	string	Required	URL of the image to process
`quality`	integer	85	Compression quality (1-100)
`max_width`	integer	2000	Maximum output width (100-5000)
`max_height`	integer	2000	Maximum output height (100-5000)

Example Request:

curl -X GET "https://api.psrestful.com/psmedx/v1/remove-background/?image_url=https://example.com/product.jpg&quality=90" \
  -H "X-API-Key: your-api-key" \
  --output product-nobg.png

Response: image/png - Binary PNG image with transparent background

Use Cases:

Prepare product images for e-commerce
Create consistent product catalogs
Prepare images for decoration previews

Decorate Product

Apply artwork to a blank product image using bounding box positioning.

Endpoint:

GET /psmedx/v1/decorate/

Query Parameters:

Parameter	Type	Default	Description
`blank_url`	string	Required	URL of the blank product image
`artwork_url`	string	Required	URL of the artwork/logo to apply
`bounding_box_json`	string	Required	JSON string with bounding box coordinates
`placement`	string	AUTO	Placement: `AUTO`, `HORIZONTAL`, `VERTICAL`
`emboss`	boolean	false	Apply emboss effect to artwork
`quality`	integer	85	Compression quality (1-100)
`max_width`	integer	2000	Maximum output width (100-5000)
`max_height`	integer	2000	Maximum output height (100-5000)

Bounding Box JSON Format:

{
  "left": 150,
  "upper": 100,
  "right": 350,
  "lower": 250
}

Example Request:

curl -X GET "https://api.psrestful.com/psmedx/v1/decorate/?blank_url=https://example.com/tshirt-blank.jpg&artwork_url=https://example.com/logo.png&bounding_box_json=%7B%22left%22:150,%22upper%22:100,%22right%22:350,%22lower%22:250%7D" \
  -H "X-API-Key: your-api-key" \
  --output decorated-product.png

Response: image/png - Decorated product image

Use Cases:

Generate product mockups with customer logos
Create decoration previews for e-commerce
Build virtual sample generators

Vectorize Image

Convert a raster image to SVG vector format.

Endpoint:

GET /psmedx/v1/vectorize/

Query Parameters:

Parameter	Type	Default	Description
`image_url`	string	Required	URL of the raster image
`colormode`	string	color	`color` or `binary`
`hierarchical`	string	stacked	`stacked` or `cutout`
`mode`	string	spline	`spline`, `polygon`, or `none`
`filter_speckle`	integer	4	Speckle filter threshold (min: 0)
`color_precision`	integer	6	Color precision level (min: 1)
`layer_difference`	integer	16	Layer difference threshold (min: 1)
`corner_threshold`	integer	60	Corner detection threshold (min: 0)
`length_threshold`	float	4.0	Path length threshold (3.5-10.0)
`max_iterations`	integer	10	Maximum iterations (min: 1)
`splice_threshold`	integer	45	Splice threshold (min: 0)
`path_precision`	integer	3	Path precision (min: 1)

Example Request:

curl -X GET "https://api.psrestful.com/psmedx/v1/vectorize/?image_url=https://example.com/logo.png&colormode=color" \
  -H "X-API-Key: your-api-key" \
  --output logo.svg

Response: image/svg+xml - SVG vector graphic

Use Cases:

Convert logos to vector format for scaling
Prepare artwork for screen printing
Create embroidery-ready files

Get Image Info

Retrieve detailed information about an image including dimensions and DPI.

Endpoint:

GET /psmedx/v1/image-info/

Query Parameters:

Parameter	Type	Description
`image_url`	string	Required - URL of the image
`original_width_in`	float	Optional - Original width in inches
`original_height_in`	float	Optional - Original height in inches

Example Request:

curl -X GET "https://api.psrestful.com/psmedx/v1/image-info/?image_url=https://example.com/artwork.png" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "fileName": "artwork.png",
  "fileSize": 245000,
  "contentType": "image/png",
  "width": 1200,
  "height": 800,
  "dpi": 300,
  "isHighRes": true
}

Color Analysis APIs

Get Top Colors

Extract the dominant colors from an image.

Endpoint:

GET /psmedx/v1/image/colors/

Query Parameters:

Parameter	Type	Default	Description
`image_url`	string	Required	URL of the image to analyze
`top_n_colors`	integer	5	Number of colors to return
`remove_bg`	boolean	false	Remove background before analysis

Example Request:

curl -X GET "https://api.psrestful.com/psmedx/v1/image/colors/?image_url=https://example.com/logo.png&top_n_colors=5&remove_bg=true" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "topNColors": 5,
  "colors": [
    {
      "rgb": [0, 82, 147],
      "hex": "#005293",
      "countPercentage": 45.2,
      "pantone": {
        "pantone": "PMS 301 C",
        "name": "Dark Blue",
        "hex": "#00538B",
        "rgb": [0, 83, 139]
      }
    },
    {
      "rgb": [255, 255, 255],
      "hex": "#FFFFFF",
      "countPercentage": 32.1,
      "pantone": {
        "pantone": "PMS White",
        "name": "White",
        "hex": "#FFFFFF",
        "rgb": [255, 255, 255]
      }
    }
  ]
}

Use Cases:

Match product colors to artwork
Suggest complementary products
Validate brand color compliance

Nearest Pantone

Find the nearest Pantone color match for hex colors.

Endpoint:

GET /psmedx/v1/nearest-pantone/

Query Parameters:

Parameter	Type	Description
`hex_color`	string[]	Required - List of hex color codes (e.g., `#005293`)

Example Request:

curl -X GET "https://api.psrestful.com/psmedx/v1/nearest-pantone/?hex_color=%23005293&hex_color=%23FF5733" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

[
  {
    "input": "#005293",
    "pantone": "PMS 301 C",
    "name": "Dark Blue",
    "hex": "#00538B",
    "rgb": [0, 83, 139],
    "distance": 8.5
  },
  {
    "input": "#FF5733",
    "pantone": "PMS 172 C",
    "name": "Orange",
    "hex": "#FF5A00",
    "rgb": [255, 90, 0],
    "distance": 12.3
  }
]

Use Cases:

Convert digital colors to print-ready Pantone
Ensure brand color consistency
Generate color specifications for suppliers

Pantone to Hex

Convert Pantone color codes to hexadecimal values.

Endpoint:

GET /psmedx/v1/pantone-to-hex/

Query Parameters:

Parameter	Type	Description
`pantone`	string[]	Required - List of Pantone codes

Example Request:

curl -X GET "https://api.psrestful.com/psmedx/v1/pantone-to-hex/?pantone=PMS%20301%20C&pantone=PMS%20172%20C" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

[
  {
    "pantone": "PMS 301 C",
    "name": "Dark Blue",
    "hex": "#00538B",
    "rgb": [0, 83, 139]
  },
  {
    "pantone": "PMS 172 C",
    "name": "Orange",
    "hex": "#FF5A00",
    "rgb": [255, 90, 0]
  }
]

Image Classification APIs

Classify Image

Analyze an image to determine if it’s blank or decorated, and extract metadata.

Endpoint:

GET /psmedx/v1/classify/

Query Parameters:

Parameter	Type	Description
`image_url`	string	Required - URL of the image to classify
`part_colors_json`	string	Optional - JSON with part-specific colors

Example Request:

curl -X GET "https://api.psrestful.com/psmedx/v1/classify/?image_url=https://example.com/product.jpg" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "fileName": "product.jpg",
  "fileSize": 125000,
  "contentType": "image/jpeg",
  "height": 800,
  "width": 600,
  "dpi": 150,
  "isHighRes": false,
  "blankOrDecorated": {
    "blank": 0.15,
    "decorated": 0.85
  },
  "singlePartOrGroup": {
    "group": 0.05,
    "singlePart": 0.95
  },
  "boundingBoxes": [
    {
      "left": 150,
      "upper": 100,
      "right": 350,
      "lower": 250
    }
  ],
  "colors": [
    {
      "rgb": [0, 0, 0],
      "hex": "#000000",
      "count": 45000,
      "name": "Black",
      "countPercentage": 35.5
    }
  ],
  "colorName": "Black"
}

Response Fields:

Field	Description
`blankOrDecorated`	Confidence scores (0-1) for blank vs decorated classification
`singlePartOrGroup`	Confidence scores for single part vs group shot
`boundingBoxes`	Detected decoration/logo areas
`colors`	Dominant colors in the image
`isHighRes`	Whether image meets high-resolution threshold

Bounding Box APIs

Find Bounding Box

Compare blank and decorated images to detect the decoration area.

Endpoint:

GET /psmedx/v1/find-bounding-box/

Query Parameters:

Parameter	Type	Description
`blank_url`	string	Required - URL of the blank product image
`decorated_url`	string	Required - URL of the decorated product image

Example Request:

curl -X GET "https://api.psrestful.com/psmedx/v1/find-bounding-box/?blank_url=https://example.com/blank.jpg&decorated_url=https://example.com/decorated.jpg" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "boundingBox": {
    "left": 150,
    "upper": 100,
    "right": 350,
    "lower": 250
  },
  "confidence": 0.95
}

Use Cases:

Automatically detect decoration areas
Create bounding box templates for new products
Validate decoration placement

Show Bounding Boxes

Draw bounding boxes on an image for visualization.

Endpoint:

GET /psmedx/v1/show-bounding-boxes/

Query Parameters:

Parameter	Type	Description
`image_url`	string	Required - URL of the image
`bounding_boxes_json`	string	Required - JSON array of bounding boxes

Bounding Boxes JSON Format:

[
  {"left": 150, "upper": 100, "right": 350, "lower": 250},
  {"left": 400, "upper": 300, "right": 550, "lower": 400}
]

Example Request:

curl -X GET "https://api.psrestful.com/psmedx/v1/show-bounding-boxes/?image_url=https://example.com/product.jpg&bounding_boxes_json=%5B%7B%22left%22:150,%22upper%22:100,%22right%22:350,%22lower%22:250%7D%5D" \
  -H "X-API-Key: your-api-key" \
  --output product-with-boxes.png

Response: image/png - Image with bounding boxes drawn

Find and Show Bounding Box

Combined operation: detect bounding box and return the image with it drawn.

Endpoint:

GET /psmedx/v1/find-and-show-bounding-box/

Query Parameters:

Parameter	Type	Description
`blank_url`	string	Required - URL of the blank product image
`decorated_url`	string	Required - URL of the decorated product image

Example Request:

curl -X GET "https://api.psrestful.com/psmedx/v1/find-and-show-bounding-box/?blank_url=https://example.com/blank.jpg&decorated_url=https://example.com/decorated.jpg" \
  -H "X-API-Key: your-api-key" \
  --output product-with-detected-box.png

Response: image/png - Blank image with detected bounding box drawn

Image Compression Options

Most image-returning endpoints support compression parameters:

Parameter	Type	Default	Description
`quality`	integer	85	JPEG/WebP quality (1-100). Higher = better quality, larger file
`max_width`	integer	2000	Maximum width in pixels (100-5000)
`max_height`	integer	2000	Maximum height in pixels (100-5000)

Notes:

PNG output maintains transparency
Images are proportionally scaled to fit within max dimensions
Quality setting primarily affects JPEG/WebP output

Error Handling

Error Response Format

{
  "detail": "Error message describing what went wrong"
}

HTTP Status Codes

Code	Meaning	Common Causes
`200`	OK	Request succeeded
`400`	Bad Request	Invalid parameters, malformed URL
`401`	Unauthorized	Missing authentication
`403`	Forbidden	Invalid API key
`404`	Not Found	Image URL not accessible
`422`	Unprocessable Entity	Invalid image format or corrupted file
`429`	Too Many Requests	Rate limit exceeded
`500`	Server Error	Processing error

Common Errors

Invalid Image URL:

{
  "detail": "Unable to fetch image from provided URL"
}

Unsupported Format:

{
  "detail": "Unsupported image format. Supported: PNG, JPEG, WebP, GIF"
}

Invalid Bounding Box:

{
  "detail": "Invalid bounding box: coordinates must be positive integers"
}

Best Practices

1. Use Appropriate Quality Settings

Web display: quality=75-85, max dimensions 1200-1500px
Print/high-res: quality=90-100, max dimensions 2000-5000px
Thumbnails: quality=70, max dimensions 300-500px

2. Cache Results

PSMEDx operations are computationally intensive. Cache processed images when possible to improve performance and reduce API calls.

3. Validate Image URLs

Ensure image URLs are publicly accessible and return valid image content before calling PSMEDx APIs.

4. Use Bounding Boxes for Consistency

Store bounding box coordinates for product templates to ensure consistent decoration placement across orders.

5. Handle Large Images

For very large images, use the max_width and max_height parameters to reduce processing time and response size.

Use Case Examples

E-commerce Product Mockup Generator

import requests
 
API_KEY = "your-api-key"
BASE_URL = "https://api.psrestful.com/psmedx/v1"
 
def generate_mockup(blank_url, logo_url, bounding_box):
    """Generate a decorated product mockup."""
    import json
 
    response = requests.get(
        f"{BASE_URL}/decorate/",
        params={
            "blank_url": blank_url,
            "artwork_url": logo_url,
            "bounding_box_json": json.dumps(bounding_box),
            "quality": 90
        },
        headers={"X-API-Key": API_KEY}
    )
 
    if response.status_code == 200:
        return response.content  # PNG image bytes
    else:
        raise Exception(f"Error: {response.json()}")
 
# Usage
bounding_box = {"left": 150, "upper": 100, "right": 350, "lower": 250}
mockup = generate_mockup(
    "https://example.com/tshirt-blank.jpg",
    "https://example.com/customer-logo.png",
    bounding_box
)

Brand Color Compliance Checker

def check_brand_colors(logo_url, brand_pantones):
    """Check if logo colors match brand guidelines."""
 
    # Get top colors from logo
    response = requests.get(
        f"{BASE_URL}/image/colors/",
        params={
            "image_url": logo_url,
            "top_n_colors": 5,
            "remove_bg": True
        },
        headers={"X-API-Key": API_KEY}
    )
 
    colors = response.json()["colors"]
 
    # Check each color against brand Pantones
    for color in colors:
        if color["pantone"] and color["pantone"]["pantone"] in brand_pantones:
            print(f"✓ {color['pantone']['pantone']} matches brand guidelines")
        else:
            print(f"✗ {color['hex']} may not match brand guidelines")

Extra APIs - Additional product and supplier APIs
Credentials API - Configure supplier credentials
Authentication - API authentication methods

Support

For additional help:

Email: devs@psrestful.com

Last Updated: January 2025 API Version: v1

Extra APIs Design Decisions

PSMEDx API

Overview

Key Capabilities

Authentication

Base URL

Image Processing APIs

Remove Background

Decorate Product

Vectorize Image

Get Image Info

Color Analysis APIs

Get Top Colors

Nearest Pantone

Pantone to Hex

Image Classification APIs

Classify Image

Bounding Box APIs

Find Bounding Box

Show Bounding Boxes

Find and Show Bounding Box

Image Compression Options

Error Handling

Error Response Format

HTTP Status Codes

Common Errors

Best Practices

1. Use Appropriate Quality Settings

2. Cache Results

3. Validate Image URLs

4. Use Bounding Boxes for Consistency

5. Handle Large Images

Use Case Examples

E-commerce Product Mockup Generator

Brand Color Compliance Checker

Related Documentation

Support