Batch Server API

Render+’s batch server uses a REST API to start, cancel or poll batches.

Routes

Route	Method	Description
/batch/recipe	POST	Submit a batch recipe
/batch/file	POST	Upload a blendfile
/batch/start	GET	Start the batch
/test	GET	Get batch server information
/batch	GET	Query the batch status
/batch/ready	GET	Determine if the server can run a batch
/batch	DELETE	Cancel the current batch
/batch/name	GET	Query the batch’s name (blend file)
/batch/jobs/{id}	GET	Query the status of a specific render job
/batch/jobs/current	DELETE	Cancel the render job currently running

Manually starting the server

The server can be started using the command line by going to the addon folder and running:

python3 server

The server has several parameters that can be used. You can get a list of them with the --help or -h parameters.

usage: server [-h] [--recipe RECIPE] [--dry] [--check] [--serve] [--port >1024] [--poll]
              [--list-gpus LIST_GPUS] [--poll-job POLL_JOB] [--cancel] [--cancel-job]
              [--stop] [--print-stats] [--no-cleanup] [--write-log] [--print-debug]
              [--version]

Render+ Batch rendering server.

optional arguments:
  -h, --help            show this help message and exit
  --recipe RECIPE       A JSON file containing a batch list.
  --dry                 Dry Run (only print stats and commands).
  --check               Check if commands and files are OK.
  --serve               Start the server.
  --port (>1024)        Change port to use when running server. Default is 7777
  --poll                Poll a running batch.
  --list-gpus LIST_GPUS
                        List available GPUs (needs a Blender binary file)
  --poll-job POLL_JOB   Poll a specific render job
  --cancel              Cancel the running batch.
  --cancel-job          Cancel the current render job.
  --stop                Stop the server.
  --print-stats         Print batch stats after finishing.
  --no-cleanup          Don't clean up temp folder after running.
  --write-log           Write a log in the logs folder.
  --print-debug         Print debug logs
  --version             show program's version number and exit

Starting a Batch

Before starting a batch we need to submit a recipe. This can be done by sending a POST request to http://localhost:[PORT]/batch/recipe.

The data sent to start a batch is called a recipe and is a dictionary with a specific set of keys. Check out the sample below. You can see how Render+ generates these by looking at the contents of the recipe module. Look for the recipe.py file inside the batch folder.

The data should be a JSON dictionary, and Content-type should be set to application/json.

Recipe sample

Here’s a sample of a Batch recipe with 1 render job. Note that jobs is a list of dictionaries.

{
  "name": "/home/user/batch.blend",
  "version": 2.2,
  "settings": {
    "rss": {
      "enabled": false,
      "path": "/home/user/feed.rss"
    },
    "global_percentage": {
      "enabled": false,
      "value": 100
    },
    "global_size": {
      "enabled": false,
      "value": [1920, 1080]
    },
    "write_log": false,
    "ignore_border": false
  },
  "blender_bin": "/bin/blender",
  "hooks": {
    "PRE_BATCH": [],
    "POST_BATCH": []
  },
  "poweroff": {
    "enabled": false,
    "action": "DISABLED"
  },
  "notifications": {
    "desktop": false,
    "sound": {
      "enabled": false,
      "file": "/home/user/.config/blender/2.80/scripts/addons/renderplus/assets/notification.ogg",
      "volume": 10
    },
    "mail": {
      "enabled": false,
      "user": "some@somemail.com",
      "pass": "password",
      "ssl": true,
      "to": "my@real-mail.com",
      "server": "smtp.mail.com"
    }
  },
  "jobs": [
    {
      "enabled": true,
      "id": 0,
      "name": "Some job",
      "output": "/home/user/render_Untitled_Scene",
      "external": false,
      "layer": "",
      "blendfile": "blendname.blend",
      "filename": "/home/user/blendname.blend",
      "animated": false,
      "engine": "BLENDER_EEVEE",
      "threads": 0,
      "hooks": {
        "PRE_JOB": [
          {
            "enabled": false,
            "cmd": "echo 'pre_job'"
          }
        ],
        "POST_JOB": [
          {
            "enabled": false,
            "cmd": "echo 'post_job'"
          }
        ]
      },
      "size": [1920, 1080],
      "blend_file": "/home/user/batch.blend",
      "scene": "Scene",
      "camera": "Camera",
      "world": "World",
      "frame_still": 1,
      "frame_start": 1,
      "frame_end": 250,
      "format": "PNG",
      "section": {
        "enabled": false,
        "x": 0,
        "y": 0,
        "width": 1,
        "height": 1
      },
      "cycles": {
        "samples": 0,
        "device": "DEFAULT"
      },
      "custom_overrides": []
    },
  ]
}

Polling

To poll the batch’s status send a GET request to http://localhost:[PORT]/batch. The response will have a HTTP status code of 200 and contain a JSON dictionary. You can also request data for a single job only using http://localhost:[PORT]/batch/jobs/[ID]. Where ID is the number of the job in the list, starting from zero.

The batch’s name is available by requesting http://localhost:[PORT]/batch/name.

Poll Response example

{
  "status" : "RUNNING",
  "times" : {
    "started" : 1545401461.3625693,
    "finished" : null,
    "rendertime" : null
  },
  "stats" : {
    "slowest_index" : null,
    "slowest_time" : null,
    "fastest_index" : null,
    "fastest_time" : null,
    "average_time" : null
  },
  "messages" : [],
  "jobs" : [
    {
      "id" : 0,
      "status" : "RUNNING",
      "times" : {
        "started" : 1545401461.3666012,
        "finished" : null,
        "rendertime" : null
      },
      "messages" : [],
      "progress" : 9.765625,
      "engine" : {
        "type" : "BLENDER_EEVEE",
        "data" : {
          "frame" : "1",
          "mem" : "127.56M",
          "elapsed" : "00:00.42",
          "samples_done" : "25",
          "samples_todo" : "256"
        }
      }
    },
    {
      "id" : 1,
      "status" : "DISABLED",
      "times" : {
        "started" : null,
        "finished" : null,
        "rendertime" : null
      },
      "messages" : [],
      "progress" : 0,
      "engine" : {
        "type" : null,
        "data" : null
      }
    },
    {
      "id" : 2,
      "status" : "QUEUED",
      "times" : {
        "started" : null,
        "finished" : null,
        "rendertime" : null
      },
      "messages" : [],
      "progress" : 0,
      "engine" : {
        "type" : null,
        "data" : null
      }
    }
  ],
  "current_job" : 0
}

Fields

• status: Can be either WAITING, RUNNING, FINISHED or, CANCELLED. If a batch has been run the status will be either FINISHED or CANCELLED. If no batch has been run the status will be WAITING.

• current_job: ID of the renderjob currently being rendered

• messages: Usually empty. Sometimes used for error messages.

• times: Start, finish and render times for the whole batch. Finished and rendertime will be null while the batch is running.

• stats: Contains average rendertime, as well as fastest and slowest jobs. All these will be null while the batch is running or if the batch is cancelled.

• jobs: A list with the status of each job.

A render job has the following keys:

• id: The ID for the render job

• status: QUEUED, DISABLED, RUNNING, FINISHED or CANCELLED

• times: Start, finish and render times for the job

• messages: Usually empty. Used for error messages when the job fails

• progress: An integer in the rage 0…100 representing the progress of the render

• engine: A dictionary containing two items: Type (name of the render engine or NON_COMPATIBLE) and data with data pulled from the render engine’s stdout

Note that NON_COMPATIBLE doesn’t mean it won’t render, but only that Render+ doesn’t know how to get information from the engine. The data key can have different keys depending on the engine.

Errors

In case of errors the routes will return an error HTTP code and a dictionary with more information. Requesting for an invalid route will return a 404.

Route	Method	HTTP Code	Description
/batch	POST	406	Wrong content-type sent (must be JSON)
/batch	POST	409	Can’t start because a batch is already running
/batch	GET	409	Can’t poll because no batch has been run
/batch/jobs/{id }	GET	409	Can’t poll because no batch has been run
/batch/jobs/{id }	GET	400	Wrong or missing index of job to poll
/batch/name	GET	409	Can’t poll because no batch has been run
/batch	DELETE	409	Can’t cancel because no batch is running
/batch/jobs/cur rent	DELETE	409	Can’t cancel because no batch is running

Here’s an example of an error response:

{
  "status" : "Not running a batch right now",
}

When a job fails it doesn’t produce an error message. It’s status is set to FAILED.

Logs

Batch server logs are different from the addon’s logs, and they are only written if you use the --write-logs parameter when starting the server. They are written to the server/log folder. The server writes a new log file every time it is started. The filename format is renderplus_[day]-[month]-[year]-[hour]-[minute]-[seconds]

Stopping the server

To stop the server press CTRL+C while it’s running.

Listing GPUs

To find a list of GPUs available to Blender in your system and their numbers you can pass the --list-gpus setting to the server.

This parameter needs a path to the Blender binary you want to use for batch rendering.

▶ python3 server --list-gpus /usr/bin/Blender

Blender 2.90.0 (hash 0330d1af29c0 built 2020-08-31 11:54:54)
Read prefs: /home/januz/.config/blender/2.90/config/userpref.blend
found bundled python: /home/januz/down/blender-2.90.0-linux64/2.90/python

GPUS AVAILABLE FOR RENDERING
--------------------------------------------------------------------------------
Radeon RX Vega 56 | Number: 0

Blender quit