The Wizart Visualizer API allows developers to programmatically access the same powerful features used in the Wizart Visualizer app. By leveraging the API, you can integrate realistic room visualizations, apply products like flooring and wall coverings, and manage interiors—all within your own applications.
This guide will walk you through the essential steps to start using the Wizart Visualizer API effectively.
1. Subscribing to the Visualizer API
The Visualizer API is available for purchase on AWS Marketplace, where you can subscribe to different pricing plans based on your usage needs. To subscribe, you'll need an AWS account. If you don’t have one, you’ll need to sign up.
How to Subscribe via AWS Marketplace
Create or Sign In to Your AWS Account: If you don’t have an AWS account, sign up for an account here. If you already have one, sign in to your account.
Visit the Visualizer API Product Page: Once signed in, go to the Visualizer API page on AWS Marketplace (insert the exact URL here).
Choose a Plan: Review the available pricing plans:
Basic Plan: Pay-as-you-go, no request limit, but a higher cost per request.
Other Plans: Includes a fixed number of requests, with additional requests charged at a lower rate than the Basic Plan.
The user can choose both the plan and the subscription duration. After selecting a plan, you will need to press the Pay button, which will direct you to a registration form.
Fill in the Registration Form: It is important to properly fill in your personal name, email, and company name in the registration form. This data will be used to create your personal account in the Wizart Administrative Panel (WAP).
Submit and Wait for Confirmation: After submitting the form and receiving a confirmation message, wait a few minutes for an email with access details and further instructions. This email will be sent to the address you provided during registration.
Complete Purchase: Follow the on-screen instructions to finalize your purchase through AWS.
Pricing and Request Limits
Each tariff plan includes a fixed number of requests per contract. If your usage exceeds this quota, additional requests will incur a fee. Payable requests include:
Uploaded Images: Each image uploaded through the API counts as one request.
Renders: Each render generated via the API counts as one request.
The Basic Plan has no limits, and you pay for each request you make, but the cost per request is higher compared to subscription plans. If you anticipate higher usage, subscription plans may offer better cost-efficiency.
2. API Reference and Postman Integration
We provide an extensive API reference that outlines all available endpoints. Whether you're fetching products, managing rooms, or applying materials, this reference is your go-to guide for interacting with the API.
Postman Integration
The API reference is Postman-ready. You can import the collection into your Postman account to start making requests immediately. This is an excellent way to familiarize yourself with the API without needing to write code upfront.
Here’s how:
Click “Run in Postman”
Import the collection into your Postman workspace.
Now you’re ready to start experimenting with the endpoints!
3. API Authentication Setup
Every request to the Wizart Visualizer API must be authenticated using your API Token.
Upon subscribing to the API, you’ll receive an API token via email.
This token should be included in every request's headers like this:
X-Api-Key: your-api-token
Additionally, the API uses Device-Tokens, which are generated by your application for each unique session. These tokens ensure that interactions are scoped to individual users or sessions, providing an extra layer of security.
Here’s how to include a Device-Token:
Device-Token: your-device-token
4. Accessing the Wizart Admin Panel
Once your API token is set up, you will also have access to the Wizart Admin Panel, a platform that helps you explore and manage products and interiors. The Admin Panel gives you a head start by providing an initial set of products and interiors shared with your account.
Each product, room, and collection has a unique identifier (UUID), which is essential for making requests through the Visualizer API. You can easily browse through the available products and interiors in the Admin Panel, find the necessary UUIDs, and use them when configuring your API requests.
In addition to reviewing the preloaded data, you’ll eventually be able to upload and manage your own products through the catalog management system, which is integrated into the Admin Panel. Once you’re familiar with how the system works, you can begin making API requests to visualize your own products and spaces.
5. Applying Products to a Room via API
The Wizart Visualizer API allows you to apply products such as wallpapers, floorings, and other materials to specific rooms. To accomplish this, follow the steps outlined below to retrieve the necessary room data, add product information, and submit the final request.
Step 1: Retrieve Room Data
Start by selecting the room you wish to work with. Every room in the Wizart system has a unique identifier (UUID) that can be obtained either through the API or the PIM interface. Once you have the room_uuid, you can request the detailed data for that room.
API Endpoint:
http
Копировать код
GET /api/v1/rooms/{room_uuid}
Example Response:
{
"uuid": "88cc386a-0897-48ea-93ed-a8aee0609253",
"title": "Wizart GO-1551 3",
"image_path": "interiors/reserved/images/4b0a7a56-2f6f-4c22-9135-8f28ea004106.jpg",
"room_type_title": "Bathroom",
"room_type_id": 9,
"width": 2560,
"height": 1706,
"surfaces": [ "wall", "floor" ],
"created_at": "24.01.2022",
"mask_name": "mask.png",
"ceiling": null,
"floor": {
"x": 52.25457191467285,
"y": 88.72437382079792
},
"walls": [
{
"x": 3,
"y": 20,
"wall_id": 0
}, {
"x": 35,
"y": 20,
"wall_id": 1
}, {
"x": 87,
"y": 20,
"wall_id": 2
}
]
}
The response provides detailed information about the room, including surfaces (walls, floor, etc.), dimensions, and unique wall identifiers. You will use this information to apply materials in the next step.
Step 2: Prepare Product Data
Once you have the room data, the next step is to gather product information for the material you want to apply to the surfaces. You can retrieve this information from the product catalog through the Wizart API.
Step 3: Prepare Request Body
Example Request Body: The example below shows how to structure the product data for a room’s walls, applying wallpaper to two walls.
/apply
request body
{
"room_data": {
"room": {
"id": "e948bc98-d955-4fb1-be42-506f3904cc18",
"image_path": "interiors/uploaded/images/9c34973f-d1cc-495d-8205-5c59a969b31e.jpg",
"mask_name": "mask.png",
"floor": {},
"ceiling": {},
"walls": [
{
"wall_id": 0,
"is_active": true,
"custom_rotation_angle": 0,
"material": {
"uuid": "bbe81b21-e9a7-43d4-bdf1-93f08ac701c1",
"code": "no_pattern",
}
}, {
"wall_id": 1,
"is_active": true,
"custom_rotation_angle": 0,
"material" {
"material_uuid"
}
"wallpaper": {
"uuid": "bbe81b21-e9a7-43d4-bdf1-93f08ac701c1",
"is_visible": true,
"product_type": {
"uuid": "5d04afb2-03bf-4be6-8bd0-0fb6a89653b5",
"code": "wallpaper"
},
"width": 0.465,
"product_width": 0.47,
"length": 8.37,
"reverse_180": false,
"mural": false,
"rapport_shift": 0,
"scene_data": {
"data": [
{
"type": "laying-pattern",
"code": "no_pattern",
"is_default": true,
"material_maps": {
"color": "pim-data/5411d399-baec-4c35-8e81-8c1cc185dee1/2055/158913.jpg"
},
"pattern_length": null,
"pattern_width": null
}
]
},
"product_length": null,
"pattern": null
}
}
]
}
}
}
This JSON body includes the following information:
Room ID: Unique identifier of the room.
Image Path: Path to the room image for rendering.
Walls: A list of walls, each with its unique
wall_id.Wallpaper: Material information, including the product UUID, width, scene data, and material maps (such as color).
Step 3: Apply Materials to the Room
After preparing the room data with the product information, send the final request to apply the materials to the selected surfaces (e.g., walls).
API Endpoint:
POST /api/v1/rooms/{room_uuid}/apply-materials
Use the room_data structure as the request body, and the API will return the room with the selected materials applied.
By following these steps, you can easily manage room configurations and customize them with various products using the Wizart Visualizer API.
5. Uploading Your Own Products to PIM
Now that you're comfortable applying textures and visualizing predefined rooms, you can upload your own products to Wizart PIM.
How PIM Integrates with the Visualizer API:
Product Data Management: The PIM system allows you to upload product images, organize collections, and maintain metadata.
Syncing with API: Once your products are in PIM, they’ll automatically be accessible through the API. This makes it seamless to visualize your products in custom rooms or applications.
Learn more in the Getting Started with Wizart PIM article.
6. API Debugging and Error Handling
Common Errors:
Invalid Token: Ensure your API Token and Device-Tokens are valid and included correctly in the headers.
Missing UUIDs: Double-check that you’re using the correct UUIDs for rooms, products, or collections.
Rate Limiting: If you’re making many requests, you may hit rate limits. Ensure you optimize your requests for performance.