---

Rendering

Render

Synchronous

GET http://clara.io/api/scenes/{uuid}/render
GET http://clara.io/api/scenes/{uuid}/render?time={TIME}&width={WIDTH}&height={HEIGHT}
GET http://clara.io/api/scenes/{uuid}/render?time={TIME}&width={WIDTH}&height={HEIGHT}&url=true

Asynchronous

POST http://clara.io/api/scenes/{uuid}/render
POST http://clara.io/api/scenes/{uuid}/render?time={TIME}&width={WIDTH}&height={HEIGHT}

URL Parameters

• uuid: the scene ID.

Optional Query Parameters

These parameters can be used to override the settings within the scene file.

• renderer: webgl. If not supplied, scene.target will be used to determine the appropriate renderer.
• time: the frame number to render
• pass: the name of the pass containing the render options
• width, height: width & height of the desired image. If not specified, either the general renderer settings or pass overrides are used.
• url: true or false, defaults to false. Only available on the synchronous API. Determines if the result upon success is an image (a binary) or an URL to that image.
• setupCommand: a command to be executed before rendering. The command must be in the form {plugin}%2f{command}, where “%2f” is equivalent to ‘/‘.
• data: optional data for setupCommand. It is available in the plugin command via options.get('data').
• format: jpeg or png. WebGL v2 default is ‘png’, unless the clip option is specified, in which case the default is mp4. The V-Ray renderer will use the format specified in the default renderer node, which has a default of jpeg. WebGL v2 also supports the video formats mp4, gif, jpeg-frames and png-frames.

Warning if renderer is not supplied, and scene.target is set to Generic (aka both V-Ray and WebGL), a WebGL render will be performed. The API server does not load the scene graph to determine which renderer is specified in the pass.

WebGL specific options:

• azimuthAngle: override camera positioning
• polarAngle: override camera positioning
• boundingRadius: override camera positioning
• subd: boolean, if enabled, will add MeshSmooth operator to all meshes.

The v2 WebGL renderer is always used. V1 WebGL rendering can only be done via the clara.io editor.

V-Ray specific options:

• gi: optional control over global illumination. Use values “on“ or “off“. Global illumination can take a long time. To get faster result, use this option to turn it off.
• cameraNode: optional camera to use when rendering. This parameter supports the name or the id (ex.: f3408a7d-0d8f-44c1-ad3e-03f2a985320a). If the camera uses special characters in its name, use the hexadecimal code (ex. ‘/‘ and ‘%2f’, ‘@’ and ‘%40’, ‘:’ and ‘%3a’).
• cameraType: optional camera type to render the scene:
  • default (default value)
  • spherical
  • box
  • fisheye
  • orthogonal
• fov: optional field of view of the camera if cameraType is used. The angle value must be between 0 and 360. If not used, the default value is the field of view of the camera in the scene used to render.
• quality: optional quality level:
  • basic
  • standard
  • high
  • maximum
• gamma: the gamma correction value. Default is 2.2. To disable gamma correction use the value of 1.0

Webgl V2 specific options:

• publishedHash: md5 hash of published content.
• configuration: render a scene with target configuration.
• renders: allows you to create multiple renders in a single job.
• clip: render an animation
  • id: id of the clip. Use the scene id to render the timeline animation.
  • fps: fps of the render result.

The renders option takes a JSON object specifying options for each render. Each key in the object is a name for the render, and the value is an object listing the options you want to vary for that render.

Output format

The output format is specified by the format option. If you create a video or a configurationList with a format of jpeg-frames or png-frames, the output is of type application/json containing links to the resulting frames.

It is highly recommended that you use asynchronous operations to render videos or V-Ray frames: synchronous operations will time out if the operation takes longer than 2 minutes.

Alternatively you can send a Accept: text/event-stream header to receive an event stream of the render job and its progress.

Asynchronous Example

See the Asynchronous Operations documentation for asynchronous examples in several languages.

Synchronous Example

These are examples of the synchronous (blocking) interface.

Rendering at frame 17:

curl "https://clara.io/api/scenes/de8891ef-6ee5-4a2c-8884-507e3648ea93/render?time=17&width=1920&height=1080&renderer=webgl" \
    -u username:c3be3060-fe81-467b-aa62-0ee42eea9c8b \
    > MyScene.jpg

Rendering with a 360 spherical camera without global illumination:

curl "https://clara.io/api/scenes/de8891ef-6ee5-4a2c-8884-507e3648ea93/render?gi=0&cameraType=spherical&fov=360&renderer=webgl" \
  -u username:c3be3060-fe81-467b-aa62-0ee42eea9c8b \
  > MyScene.jpg

Rendering with configuration:

const png = await fetch(
  `https://clara.io/api/scenes/de8891ef-6ee5-4a2c-8884-507e3648ea93/render?configuration=${JSON.stringify(
    { color: 'red', style: 'Italia' }
  )}`
);

Rendering with renders

const manifest = await fetch(
  `https://clara.io/api/scenes/de8891ef-6ee5-4a2c-8884-507e3648ea93/render?renders=${JSON.stringify(
    {
      redChair: { configuration: { color: 'red' } },
      blueChair: { configuration: { color: 'blue' } },
    }
  )}`
);

Rendering a video:

const mp4 = await fetch(
  `https://clara.io/api/scenes/de8891ef-6ee5-4a2c-8884-507e3648ea93/render?clip=${JSON.stringify(
    { id: 'de8891ef-6ee5-4a2c-8884-507e3648ea93', fps: 30 }
  )}&format=mp4`
);

Clara Node SDK

When using the Clara Node SDK:

$ clara scenes:render [options]

---