Introduction

The Upload User Photos API is a core service within the Artifi platform that enables users to upload custom images for use in product personalization and other media-driven workflows. It plays a critical role in scenarios where end users need to incorporate their own visual assets such as photos, logos, or artwork into customizable products like t-shirts, mugs, canvas prints, and promotional items.

This API accepts image files via multipart form data and performs a series of validations and processing steps to ensure compatibility with the platform configuration. Uploaded files are validated against predefined rules, including supported file formats, file size limits, and image dimensions. Once validated, the system processes the image by generating optimized versions such as standard and thumbnail sizes for efficient rendering across different use cases.

Use Cases

• Product Personalization

Allows customers to upload their own images (photos, logos, artwork) while customizing products such as t-shirts, mugs, phone cases, canvas prints, and other promotional items. The uploaded image can be applied to the design canvas.

• User Profile Image Upload

Enables users to upload profile pictures or avatars within applications, ensuring proper validation and optimized image storage for consistent display across the platform..

• Artwork Submission for Custom Printing

Facilitates designers and customers in uploading high-resolution artwork files (including vector formats) for printing on physical products, ensuring quality output.

• Marketing and Campaign Assets

Allows internal teams or users to Upload User Photos for use in marketing campaigns, banners, and promotional creatives within the platform.

• Thumbnail and Preview Generation

Automatically generates optimized versions of uploaded images (such as thumbnails) for quick previews in product design tools and galleries.

• Multi-Format Image Handling

Supports uploading of both raster and vector image formats, enabling flexibility for different use cases such as high-quality printing (vector) and quick previews (raster).

• Reusable Image Library

Stores uploaded images so users can reuse them across multiple designs or sessions without needing to upload the same asset repeatedly.

• Integration with Design Workflows

Seamlessly integrates with the product design editor, allowing uploaded images to be instantly available for positioning, scaling, and customization within the design interface.

API Details

curl --location --request POST \

'https:// {base-url} /api/2/UploadPhoto/UploadUserPhotos?frontAppUserId=user_id&websiteId= your_website_id &webApiClientKey= your_client_key &dpi=dpi&isGuest=isGuest&oldExternalUserId=oldExternalUserId isColorDetect= is_color_detect &isTransparent= is_transparent &minimumColorPercentage= minimum_color_percentage& removedAllWhiteBackground=removed_all_whitebackground' \

--form 'postedFile=@"/path/to/image.png"'

Query Parameters

Success Responses
{ 
"Response": "Success", 
"Message": "", 
"Data": { 
"Id": 340927, 
"ImageName": "ArtifiLogo.png", 
"UniqueName": "...", 
"Width": 355, 
"Height": 142, 
"DPI": 96, 
"Extension": ".png", 
"MimeType": "image/png", 
"PhotoCode": "340706", 
"OriginalURL":"OriginalURL", 
"StandardURL": "StandardURL", 
"ThumbnailURL": "ThumbnailURL”

"Colors": "[#FFFFFF,#4D85A0,#6DBD4C]",

  "IsTransparent": false 
}, 
"ErrorCode": "" 
}

On Error

On error, this method will call back the JavaScript method in the website which is specified in the "errorCallback" parameter with errorMessage.

Error Message:

{

  "Response": "Error",

  "Message": "Internal server error occurred , while processing image",

  "Data": null,

  "ErrorCode": "500"

}

Error Code List :  (Click Here)

Q&A

Q1. What does the Upload User Photos API do? 
The Upload User Photos API allows users to upload custom image files to the system for use in product personalization, and other media-related workflows.

Q2. What type of files can be uploaded using this API? 
The API supports multiple image formats, including both raster (e.g., PNG, JPG) and vector formats, as long as they meet the platform’s validation rules.

Q3. How is the image uploaded to the API? 
Images are uploaded using a multipart/form-data request with the file passed in the postedFile parameter.

Q4. What validations are performed on the uploaded image? 
The API validates file format, file size, dimensions, and optionally DPI (dots per inch) to ensure compatibility with the platform.

Q5. What happens if the uploaded image does not meet the DPI requirement? 
If a DPI value is provided and the uploaded image has a lower DPI, the upload request will be rejected.

Q7. What does the API return on a successful upload? 
The API returns metadata about the uploaded image, including dimensions, DPI, file type, unique identifiers, and URLs for original, standard, and thumbnail versions.

Q8. Are multiple image versions generated after upload? 
Yes, the system automatically generates optimized versions such as standard and thumbnail images for efficient rendering.

Q9. Is authentication required to use this API? 
Yes, the request must include websiteId and webApiClientKey parameters for validation and authentication.

Q10. Can uploaded images be reused later? 
Yes, uploaded images are stored and can be reused across multiple designs or sessions without needing to upload them again.

Q11. What type of response format does the API return? 
The API returns a structured JSON response containing status, message, data object, and error code.

Q12. What is the purpose of the isColorDetect parameter? 
The isColorDetect parameter is used to enable prominent color detection for the uploaded image. When set to true, the API analyzes the visible pixels in the image and returns detected color values in HEX format.

Q13. How does minimumColorPercentage work with color detection? 
The minimumColorPercentage parameter applies only when isColorDetect is set to true. It defines the minimum percentage of the image that a color must cover before it is included in the response. Lower values return more colors, while higher values return only the most dominant colors.

Q14. What does the isTransparent parameter return? 
The isTransparent parameter enables transparency detection. When set to true, the API checks whether the uploaded image contains transparent pixels and returns the result as a boolean value in the response.

Q15. Where can I find details about error codes?
Error code details are documented separately and should be referenced through the provided Error Code documentation link.