Data API background and shading options


(Umaptechnologies) #1

When uploading a modal using the data API we're attempting to set shading to "shadeless" and also to use a custom background image.

Is this possible using the data API? Here's the data API documentation link but it doesn't reveal what I might do:

However, there's some legacy Python code in our application that shows an attempt to set shading - shown below. We're not sure where this came from but unfortunately it doesn't work. Any ideas? Is there some documentation somewhere that I'm missing? Any help is most appreciated. (we have a Pro account)

        # Turn off shading on the model
        url  = '' % (model_id, self.api_token)
        data = {
            'options' : {
                'shading' : {
                    'type' : 'shadeless',
                    'renderer' : 'classic'
        response = requests.patch(url, data=data, verify=True)

        # Confirm the request succeeded
        print "Response.status_code: ", response.status_code
        if response.status_code !=
            self.logger.error("%s Failed to set rendering mode of the model! Response: %s", image_set_id, response.json())

            return ([], [message])

3D settings controlled via API
Help changing watermark and background image

It's possible with the API, but it's unstable and undocumented. Eventually it will be part of the public API, but for now it's a bit of a hack.

After a model is uploaded and processed successfully, you need to send an additional PATCH request to change options. Here's a quick example in JavaScript. Again, this is unstable and subject to change without warning.

var options = {
      "options": {
        "background": {
          "color": [0.2, 0.3, 0.4],
          "enable" : 'none', // 'fixed', 'environment', 'color'
          "uid: 'fixed_bg_uid' // you will need enable: 'fixed', you can find the bg UID by inspecting the data-value of its thumbanail in the editor
        "shading": {
          "type": "shadeless",

var data = JSON.stringify( options );

  url: '' + MODEL_UID + '?token=' + API_TOKEN,
  data: data,
  type: 'PATCH',
  contentType: 'application/json',
  traditional: true,

  success: function( response ) {
    console.log( 'PATCH successful: ' + model );

  error: function( response ) {
    console.log( 'Description PATCH failed: ' + response );

The model uses an old version of the renderer

And a quick and dirty Python example:

import requests
import json

headers={'content-type': 'application/json'}
data = {'options' : {'shading' : {'type' : 'shadeless','renderer' : 'classic'}}}

r = requests.patch('', headers=headers, data=json.dumps(data))

print r.status_code

(Umaptechnologies) #4

James, thanks so much! Can I bug you once more? Is there a way to upload a custom background image along with those other options?

thanks again,

(Umaptechnologies) #5

oh oh sorry I see now about the UID. sorry I missed that.


At the moment, you can't upload a new background with the API, it needs to already be on your account.

(Umaptechnologies) #7

Thanks again James. Looks like we got what we needed. :smile:

(Wolfprint3d) #8

Thanks for that @james , I was able to change shading settings and the background to a custom image, but I also need the lights to be turned on from the lighting tab. Is there a way to set lighting settings similarly?

I know this is a short term solution, but it would be really handy until the new API version is released.
I'm using Python btw.


Yes, I recommend saving settings in the editor with the lights you need and looking at the Network request for the lighting options JSON.

(Wolfprint3d) #10

Thanks for the idea, I just found a solution for my problem. I use the default settings, only need the lights to be turned on.
So the solution is to just add this to data:



@umaptechnologies Looks like you're doing lots of tests. How's it going?

(Umaptechnologies) #12

Hey @james, thanks again for all your support. I know you said this solution was a bit of a hack, but we've noticed this error message cropping up intermittently since we got our new error reporting online:

"Your changes couldn't be saved because the model uses an old version of the renderer. Please go the editor(link) and save the settings to fix this."

It comes up for shading and background both. Going to the edit page as it suggests, it seems the model defaults to PBR as its renderer. Since it only comes up sometimes we figured this wasn't an intentional API change. Do you have any ideas how we could make this behavior work more consistently? Thanks.

(Xiuming Zhang) #13

Hi James,

What is the current version of this "quick and dirty Python example"? It doesn't seem to work any more.

I tried v2

r = requests.patch('' % (UID, token), headers=headers, data=json.dumps(settings))

which returns me status_code 400,

and v3

r = requests.patch('' % (UID, token), headers=headers, data=json.dumps(settings))

which returns me status_code 204.

Neither works.

(Xiuming Zhang) #14

I solved this problem myself. Posting it here for the sake of future readers.

I ended up adapting this script to patch correctly.


Yep, the most up-to-date documentation and samples can be found on our developer pages:



To simplify the UI and avoid maintaining multiple rendering modes, we’re planning to remove Classic from the editor. We need to assess how this will affect developers.

Is anyone using the API to set Classic? Shadeless PBR will look identical to Classic.