blender-render

blender-render

Use render_scene for short stills. Use start_render_job for animation or multi-layer EXR or display-ready PNG output so the interactive Blender process remains responsive; poll with get_render_job and cancel only through the returned job id.

Use start_multiview_render_job for a bounded camera list (up to 8) and beauty/wire PNG deliverables. It saves an isolated copy of the current scene without changing the live filename, selection, materials, or settings. The worker uses factory startup with automatic scripts disabled. External assets must remain accessible; add-on-generated render dependencies are not loaded. Beauty uses the saved render engine (Cycles uses CPU) but bypasses compositor and sequencer to contain file output. Resolution is explicit and border rendering is disabled. Cameras render the current saved frame; camera animation markers are not used to select views.

Wire shows original mesh edges as physical tubes over the same unmodified mesh surfaces. Modifiers and shape keys are disabled, non-mesh geometry is omitted, and hidden render objects remain hidden. This is source topology, not evaluated modifier topology or a screen-space overlay. Radius is in local object units and scales with the object. The wire pass uses Cycles CPU. Requests exceeding the explicit max_source_edges budget (default 100,000; maximum 500,000) are rejected. Each PNG is decoded by Blender, dimension checked, and hashed; status reads verify the entire file hash. Failed images retain individual errors and do not make the batch successful.

Render device for background jobs

start_render_job has no device of its own: device defaults to null, so no --cycles-device flag reaches the worker and the job renders with the Cycles device saved in the .blend file (scene.cycles.device), which is CPU for a new scene. Leave it unset unless the caller explicitly asks for a specific device — it is the only portable choice, because a forced value overrides the artist's scene.

Pass one of OPTIX, CUDA, HIP, ONEAPI, METAL, CPU only to override. OPTIX needs an NVIDIA GPU and is supported on Windows and Linux only, so it always fails on macOS and on any host without an NVIDIA GPU.

When a job fails, get_render_job attaches the worker's log tails as stderr_tail and stdout_tail (Blender puts the device error on stdout on some platforms and on stderr on others). The message then reports, in order: failure_hint when the requested device is the cause; the job's own error when it recorded one, as a recovered multiview receipt does; otherwise a pointer at the two tails.

The device advice is kind-specific. For an animation job it says to retry start_render_job with device="CPU". A multiview job gets different advice, because start_multiview_render_job takes no device argument and resubmitting through start_render_job would drop the camera and pass list — change scene.cycles.device and resubmit the multiview job instead.

A recovered job reads only log files that sit directly inside job_directory and are not symlinks: the directory is caller-supplied, and a receipt there proves nothing about the files beside it.

Output configuration

Typed tools for the settings that decide what ends up on disk. Reach for them instead of raw scripting when the task is about AOVs, denoise, file format, or rendering a sub-rectangle:

Tool	Description
get_view_layer_passes	Report which AOVs are enabled on a view layer
set_view_layer_passes	Turn AOVs on or off
set_render_denoise	Cycles denoise: enable, denoiser, input passes, prefilter, GPU
get_render_output	Report path, format, color mode/depth, EXR codec, multi-layer mode
set_render_output	Set path, format, color mode/depth, EXR codec, multi-layer EXR
set_render_region	Enable border rendering with normalised 0..1 coordinates
clear_render_region	Disable border rendering and reset to the full frame
get_render_status	Frame range, frame count, and the state that affects output

set_view_layer_passes complements blender-scene-assembly's configure_view_layer, which can only switch passes on. Use this one when a pass has to be turned off again. Passes listed in neither enable nor disable keep their current state.

Denoise settings are Cycles-only; EEVEE ignores them.

Multi-layer EXR is a property of the container format, so multilayer: true switches image_settings.file_format to OPEN_EXR_MULTILAYER and clears render.use_single_layer (render every layer). multilayer: false drops back to OPEN_EXR when the container was multi-layer. use_single_layer alone only controls which layers are rendered — it cannot produce a multi-layer file. Both read tools report multilayer derived from the output container. Blender builds exposing image_settings.media_type require MULTI_LAYER_IMAGE before assigning OPEN_EXR_MULTILAYER; both typed settings tools and detached render workers set that media type first. Returning to PNG or single-layer EXR selects IMAGE first. Older builds retain their file-format API. Workers configure native RNA with a bounded expression before rendering, without requiring an adapter installation in the detached process or changing the live scene's format for an explicit job override. When neither scene_name nor view_layer_name is given, these tools operate on bpy.context.view_layer.

Poll using the existing get_render_job(job_id) and retain job_directory. After an adapter restart, get_render_job(job_id, job_directory) recovers terminal receipts; a nonterminal receipt returns unknown with its last recorded state because no live process handle has been observed. No PID from a disk file is trusted. Multiview cancellation writes an owned marker and is cooperative between images; it cannot interrupt an in-progress render. cancel_render_job accepts job_directory for the same recovery case.