rooom Developers

Appearance

Automated HD-Renderings ​

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.

INFO

It is currently only possible to request an API token through our support team, in the future you will be able to create tokens through your dashboard under settings.

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) Viewer-ID

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 ​

bash
curl -X 'GET' \
  'https://api.rooom.com/renderings/templates/product' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer [API_TOKEN]'
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 ​

bash
curl -X 'GET' \
  'https://api.rooom.com/renderings/formats' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer [API_TOKEN]'
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.

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 ​

bash
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"
}'
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

Rendering sample
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

Copyright © 2024 // rooom.com