Client

class dazpy.DazClient(host='127.0.0.1', port=18811, token=None, timeout=30.0)

Bases: object

HTTP client for the DAZ Studio Script Server.

Handles authentication, request serialisation, and response mapping for all server endpoints. The token is loaded automatically from ~/.daz3d/dazscriptserver_token.txt when token is None.

Parameters:

• host (str) – Hostname or IP address of the Script Server.

• port (int) – Listening port of the Script Server.

• token (str | None) – API token. Pass an empty string to disable authentication or None to auto-load from the default token file.

• timeout (float) – Per-request HTTP timeout in seconds.

Example:

client = DazClient()                          # default 127.0.0.1:18811
client = DazClient(token="my-secret-token")   # explicit token

execute(script, args=None)

Execute a DazScript string synchronously.

Parameters:

• script (str) – DazScript source code to execute.

• args (object) – Optional value passed into the script as getArguments()[0]. Must be JSON-serialisable.

Returns:

The execution result containing the script return value and any console output.

Raises:

• ConnectionError – If the server cannot be reached.

• AuthenticationError – If the token is invalid or the IP is blocked.

• ScriptSyntaxError – If the script contains a parse error.

• ScriptRuntimeError – If the script raises a runtime exception.

• TimeoutError – If the request exceeds timeout seconds.

Return type:

ExecutionResult

execute_file(script_file, args=None)

Execute a .dsa script file that resides on the DAZ Studio host.

Parameters:

• script_file (str) – Absolute path to the .dsa file on the server host.

• args (object) – Optional argument passed to the script.

Returns:

The execution result.

Raises:

• ConnectionError – If the server cannot be reached.

• AuthenticationError – On auth failure.

• ScriptSyntaxError – On parse error.

• ScriptRuntimeError – On runtime error.

• TimeoutError – On HTTP timeout.

Return type:

ExecutionResult

execute_async_submit(script, args=None)

Submit a script for asynchronous execution and return immediately.

Parameters:

• script (str) – DazScript source code.

• args (object) – Optional argument for the script.

Returns:

The server-assigned request_id string. Use it with get_request_status() or get_request_result() to poll for the outcome.

Raises:

• ConnectionError – If the server cannot be reached.

• AuthenticationError – On auth failure.

Return type:

str

get_request_status(request_id)

Return the current status of an async request.

Parameters:

request_id (str) – The ID returned by execute_async_submit().

Returns:

"queued", "running", "completed", "failed", "cancelled", or "not_found".

Return type:

A dict with at least a "status" key. Possible values

get_request_result(request_id, wait=False, wait_timeout=30)

Fetch the result of a completed async request.

Parameters:

• request_id (str) – The ID returned by execute_async_submit().

• wait (bool) – If True, the server will long-poll until the request completes or wait_timeout is reached.

• wait_timeout (int) – Maximum number of seconds the server should wait before returning (only relevant when wait is True).

Returns:

A dict containing success, result, output, error, duration_ms, and status keys.

Return type:

dict

cancel_request(request_id)

Cancel a queued or running async request.

Parameters:

request_id (str) – The ID returned by execute_async_submit().

Returns:

True if the server confirmed cancellation, False otherwise.

Return type:

bool

render_submit(output_path, *, figure=None, morphs=None, figures=None, width=0, height=0, camera='', engine='', iray_samples=0, reset_morphs=False)

Submit a render job and return immediately.

Parameters:

• output_path (str) – Absolute path on the DAZ Studio host to write the image.

• figure (str | None) – Label of the figure to configure morphs on.

• morphs (dict | None) – Morph values to apply {label: value}.

• figures (list | None) – List of {"name": ..., "morphs": {...}} dicts for multi-figure scenes.

• width (int) – Image width in pixels (must be paired with height).

• height (int) – Image height in pixels (must be paired with width).

• camera (str) – Camera label to render from.

• engine (str) – Render engine ("iray", "3delight", "filament").

• iray_samples (int) – iRay sample count (0 = use scene default).

• reset_morphs (bool) – If True, reset all morphs to defaults before applying.

Returns:

A dict with request_id, status ("queued"), and submitted_at keys.

Raises:

• ConnectionError – If the server cannot be reached.

• AuthenticationError – On HTTP 401/403.

Return type:

dict

render_batch_submit(variants, base=None)

Submit a batch render job and return immediately.

Parameters:

• variants (list) – List of variant dicts, each with at least output_path. Supported keys mirror render_submit() optional fields.

• base (dict | None) – Optional shared defaults applied to all variants.

Returns:

A dict with batch_id, request_ids (list), and total keys.

Raises:

• ConnectionError – If the server cannot be reached.

• AuthenticationError – On HTTP 401/403.

Return type:

dict

cancel_render(request_id)

Cancel a queued or running render job.

Parameters:

request_id (str) – The request_id from render_submit() or a RenderResult with wait=False.

Returns:

True if the server confirmed cancellation, False otherwise (already finished, not found, or connection error).

Return type:

bool

stream_render_progress(request_id, stream_timeout=305.0)

Open the SSE progress stream for a render request.

Returns a streaming requests.Response on success, or None if the endpoint is unavailable. Callers must close the response when done.

export_usd_submit(output_path, *, include_geometry=True, include_materials=True, include_skeleton=False, include_morphs=False, include_lights=False, include_camera=False)

Submit a USD export job and return immediately.

Parameters:

• output_path (str) – Absolute path on the DAZ Studio host where the .usda file should be written.

• include_geometry (bool) – Export mesh geometry (default True).

• include_materials (bool) – Export PBR material prims (default True).

• include_skeleton (bool) – Export UsdSkel armature and skin weights.

• include_morphs (bool) – Export active morphs as UsdSkelBlendShape prims.

• include_lights (bool) – Export scene lights using UsdLux prims.

• include_camera (bool) – Export the active render camera as UsdGeomCamera.

Returns:

A dict with job_id, status ("queued"), and submittedAt keys.

Raises:

• ConnectionError – If the server cannot be reached.

• AuthenticationError – On HTTP 401/403.

Return type:

dict

get_usd_export_status(job_id)

Poll the status of a USD export job.

Parameters:

job_id (str) – The ID returned by export_usd_submit().

Returns:

A dict with job_id, status, and (on completion) outputPath or error keys.

Raises:

• ConnectionError – If the server cannot be reached.

• AuthenticationError – On HTTP 401/403.

Return type:

dict

status()

Return the server status dict from GET /status.

health()

Return the health check dict from GET /health.

metrics()

Return the metrics dict from GET /metrics.