Automated HD-Renderings

WARNING

The "HD renderings from products" feature is only enabled for certain users. Please contact our support team to request access to this feature.

It's possible to control and automate the process of generating HD-renderings of a product via the REST-API.

REST-API

Authentication

A bearer token (API_TOKEN) is required to successfully send the API calls.
You can create a new token in the API section in the settings via your dashboard.

API calls

The following API calls are needed for this tutorial:

1. GET existing renderings
2. GET rendering templates
3. GET rendering formats
4. START single rendering
5. START bulk renderings
6. DELETE rendering

Prerequisites

It is important that a viewer-id, a template and a format are sent with each rendering call. To find out the correct values the following three steps are necessary.

INFO

Currently it is only possible to choose from the existing templates and formats. Own definitions must be deposited via the support team to their account.

1. Get viewer-id

To find the corresponding viewerId (VIEWER_ID), you have two possible ways.

Via dashboard

• Go to your dashboard
• Click on the specific product-card on the three-dotted icon (menu)
• Select "Share"
• The modal show the product-viewer as iframe and below the link
• Copy the last part from the url (hex-string)

Via REST-API

Another option is to query your viewers via the API as well. You can have all available viewers returned to you and search for the right item yourself.
GET my products

2. Get template

Use the following API call to display all templates that are available for you.
GET rendering templates

For the identification of the correct format the field id is required.

Example

Request (cURL)

curl -X 'GET' \
  'https://api.rooom.com/renderings/templates/product' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer [API_TOKEN]'

Request (JSON)

[
  {
    "title": "Product top",
    "type": "product_template",
    "render_settings": {
      "lightpath_bounces": {
        "total": 12,
        "diffuse": 4,
        "glossy": 4,
        "transmission": 12,
        "volume": 0,
        "transparent": 8
      },
      "environment": {
        "location": [0, 0, 0],
        "rotation_euler": [0, 0, 0],
        "scale": [1, 1, 1],
        "environment_lighting": true,
        "y_up": false
      },
      "active_camera": "myCamera",
      "cameras": [
        {
          "name": "myCamera",
          "object_name": "myCamera",
          "rotation_mode": "TARGET_VECTOR_ANGLE_AND_MARGIN",
          "camera_to_target_angle": [0, 0, 0],
          "camera_to_target_margin": 33,
          "target_vector": [0, 1, 0],
          "focal_length": 85,
          "dof_use": false,
          "dof_aperture_fstop": 2.8,
          "dof_aperture_blades": 0,
          "dof_aperture_rotation": 0,
          "dof_aperture_ratio": 1,
          "exposure": 1,
          "y_up": true
        }
      ],
      "render_settings": {
        "resolution_x": 1024,
        "resolution_y": 1024,
        "samples": 128,
        "use_denoising": false,
        "denoiser": "OPENIMAGEDENOISE",
        "file_format": "PNG",
        "engine": "CYCLES",
        "device": "GPU",
        "device_type": "OPTIX",
        "transparent_background": true,
        "shadow_catcher": true
      },
      "objects": [
        {
          "scale": [1, 1, 1],
          "filename": "*"
        }
      ]
    },
    "id": "643669fa7a536b3bc81d2a26",
    "user_id": null,
    "created": 0
  },
  {
    "title": "Product 30 hero",
    "type": "product_template",
    "render_settings": {
      "lightpath_bounces": {
        "total": 12,
        "diffuse": 4,
        "glossy": 4,
        "transmission": 12,
        "volume": 0,
        "transparent": 8
      },
      "environment": {
        "location": [0, 0, 0],
        "rotation_euler": [0, 0, -0.5235987901687622],
        "scale": [1, 1, 1],
        "environment_lighting": true,
        "y_up": false
      },
      "active_camera": "myCamera",
      "cameras": [
        {
          "name": "myCamera",
          "object_name": "myCamera",
          "rotation_mode": "TARGET_VECTOR_ANGLE_AND_MARGIN",
          "camera_to_target_angle": [81, 0, -30],
          "camera_to_target_margin": 33,
          "target_vector": [0, 1, 0],
          "focal_length": 85,
          "dof_use": false,
          "dof_aperture_fstop": 2.8,
          "dof_aperture_blades": 0,
          "dof_aperture_rotation": 0,
          "dof_aperture_ratio": 1,
          "exposure": 1,
          "y_up": true
        }
      ],
      "render_settings": {
        "resolution_x": 1024,
        "resolution_y": 1024,
        "samples": 128,
        "use_denoising": false,
        "denoiser": "OPENIMAGEDENOISE",
        "file_format": "PNG",
        "engine": "CYCLES",
        "device": "GPU",
        "device_type": "OPTIX",
        "transparent_background": true,
        "shadow_catcher": true
      },
      "objects": [
        {
          "scale": [1, 1, 1],
          "filename": "*"
        }
      ]
    },
    "id": "6447b423999df92ac86c405b",
    "user_id": null,
    "created": 0
  }
]

3. Get format

Use the following API call to display all formats that are available for you.
GET rendering formats

For the identification of the correct format the field key is required.

Example

Request (cURL)

curl -X 'GET' \
  'https://api.rooom.com/renderings/formats' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer [API_TOKEN]'

Request (JSON)

[
  {
    "key": "web",
    "title": "Web",
    "print_definition": "A4, 72 dpi",
    "render_settings": {
      "resolution_x": 2000,
      "resolution_y": 2000,
      "file_format": "JPG"
    }
  },
  {
    "key": "print",
    "title": "Print",
    "print_definition": "A3, 300 dpi",
    "render_settings": {
      "resolution_x": 5000,
      "resolution_y": 3510,
      "file_format": "TIF"
    }
  },
  {
    "key": "poster_medium",
    "title": "Plakat Medium",
    "print_definition": "A2, 300 dpi",
    "render_settings": {
      "resolution_x": 7020,
      "resolution_y": 5000,
      "file_format": "TIF"
    }
  },
  {
    "key": "poster_big",
    "title": "Plakat Big",
    "print_definition": "A1, 300 dpi",
    "render_settings": {
      "resolution_x": 10000,
      "resolution_y": 7020,
      "file_format": "TIF"
    }
  }
]

Create renderings

In the previous step we gathered all the necessary information, and now we can build and start the rendering calls, single or in bulk. Both rendering types are asynchronous and only return a response when the rendering has been accepted and sent to the pipeline.

• Single Rendering
• Bulk Rendering
• Retrieve Rendering Status

For this example we use the following values:

• template_id = 6447b423999df92ac86c405b
• format_key = web

Single rendering

To start a single rendering of a product the following API call is necessary.
START single rendering

Example

Request (cURL)

curl -X 'POST' \
  'https://api.rooom.com/viewers/[VIEWER_ID]/renderings' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer [API_TOKEN]' \
  -H 'Content-Type: text/json' \
  -d '{
  "template_id": "6447b423999df92ac86c405b",
  "format_key": "web"
}'

Request (JSON)

{
  "status": "ok",
  "renderings": [
    {
      "title": "Avocado_Product_Rendering",
      "type": "product",
      "render_settings": {
        "lightpath_bounces": {
          "total": 12,
          "diffuse": 4,
          "glossy": 4,
          "transmission": 12,
          "volume": 0,
          "transparent": 8
        },
        "environment": {
          "location": [0, 0, 0],
          "rotation_euler": [0, 0, -0.5235987901687622],
          "scale": [1, 1, 1],
          "environment_lighting": true,
          "y_up": false
        },
        "active_camera": "myCamera",
        "cameras": [
          {
            "name": "myCamera",
            "object_name": "myCamera",
            "rotation_mode": "TARGET_VECTOR_ANGLE_AND_MARGIN",
            "camera_to_target_angle": [81, 0, -30],
            "camera_to_target_margin": 33,
            "target_vector": [0, 1, 0],
            "focal_length": 85,
            "dof_use": false,
            "dof_aperture_fstop": 2.8,
            "dof_aperture_blades": 0,
            "dof_aperture_rotation": 0,
            "dof_aperture_ratio": 1,
            "exposure": 1,
            "y_up": true
          }
        ],
        "render_settings": {
          "resolution_x": 2000,
          "resolution_y": 2000,
          "samples": 128,
          "use_denoising": false,
          "denoiser": "OPENIMAGEDENOISE",
          "file_format": "JPG",
          "engine": "CYCLES",
          "device": "GPU",
          "device_type": "OPTIX",
          "transparent_background": true,
          "shadow_catcher": true
        },
        "objects": [
          {
            "scale": [1, 1, 1],
            "filename": "mesh.3afa42.glb"
          }
        ]
      },
      "created": 1695994050,
      "status": "queued",
      "service": "rooom-renderservice",
      "format": "web",
      "pipeline": [],
      "id": "6516d0c2a928050ded36df08",
      "viewer_id": "646c90e8832efe2faf536d2f",
      "template_id": "6447b423999df92ac86c405b",
      "template_title": "Product 30 hero"
    }
  ]
}

Rendering result

Downscaled rendering for documentation-page from 2048px to 512px

Bulk rendering

To start multiple renderings in one call, you can use the api-call, as bulk.
START bulk renderings

Retrieve Rendering

To query the status of a finished or processing rendering, the following call is necessary.
GET existing renderings

All available renderings of the product are returned, and you have the possibility to find the corresponding element in the list with the rendering ID.

Delete renderings

If the rendering is no longer needed after processing, it can also be deleted via the API. The following API call is necessary for this:
DELETE rendering