WorldJen

Appearance

SDK and CLI ​

The WorldJen Python SDK lets you create runs and manage resources from code or the command line. Use it for automation, CI, or scripting against the WorldJen API.

Installation ​

Install the core package for programmatic runs and CLI (runs, models, API keys):

sh
pip install worldjen

With uv:

sh
uv pip install worldjen

To operate the runner (GPU worker) from the CLI, install the optional runner extra:

sh
pip install worldjen[runner]

or uv pip install worldjen[runner]. The runner requires a Linux system with systemd.

Configuration ​

Set your API key via environment variable or in code:

  • WORLDJEN_API_KEY — Required for creating runs and for CLI commands that read/write data.
python
import worldjen
worldjen.config(api_key="your-api-key")

Using the SDK in Python ​

Pass a pipeline (callable or object with generate or infer), dimensions, and optional run name and model ID. The SDK creates the run, generates and uploads videos, and can wait for evals.

python
result = worldjen.run(
    my_pipeline,
    dimensions=[worldjen.Dimensions.SUBJECT_CONSISTENCY],
    run_name="my-eval",
    model_id="my-org/my-model",
    wait_for_evals=True,
)
print(result.run_id, result.status, result.eval_results)

See the PyPI package and SDK README for full API and dimension options.

CLI overview ​

All commands that need authentication use WORLDJEN_API_KEY or --api-key.

Runs ​

worldjen runs create matches the dashboard: it enqueues work on a worker. You must pass --runner-id and --model-id (MongoDB ids from the app). Optional --run-instructions accepts inline JSON or a path to a .json file (pipeline options for the runner).

  • worldjen runs create --name NAME --dimensions DIM1,DIM2 --runner-id RUNNER_ID --model-id MODEL_ID [--run-instructions JSON_OR_PATH]
  • worldjen runs list — list runs (optional --status, --page, --limit)
  • worldjen runs get RUN_ID — run metadata
  • worldjen runs cancel / delete / logs / csv / videos / download-videos

Dimensions ​

worldjen dimensions list returns all available evaluation dimensions.

  • worldjen dimensions list — list all dimensions with IDs and descriptions
  • worldjen dimensions list --json — machine-readable output for agents

Models ​

  • worldjen models list — your models
  • worldjen models list-base / list-ref
  • worldjen models create --name NAME --provider P --hf-repo-id REPO --type text_to_video — add --hf-token TOKEN or WORLDJEN_HF_TOKEN for private repos
  • worldjen models delete MODEL_ID

API keys ​

worldjen api-keys list. Create and revoke keys in the dashboard.

Runner ​

Requires worldjen[runner]. Backend commands act on your account's runner resources (API). Local commands act on this machine (config file, systemd); Linux with systemd is required for install/start/stop/logs.

  • Backend: worldjen runner create [--name NAME] — create runner, register this machine, install and start service
  • Backend: worldjen runner delete [--runner-id ID] — delete runner from account and uninstall local service
  • Backend: worldjen runner list — list your runners
  • Local: worldjen runner register --token TOKEN — register this machine with a token from the web UI
  • Local: worldjen runner install / start / stop / status (systemd) / uninstall / logs

worldjen runner delete removes the runner in the API, stops and uninstalls the local systemd unit, and deletes local runner.conf (and key) so you can run runner create again on the same machine.

worldjen runner list includes a status column when the API provides it. Many commands support --json for machine-readable output.

SDK vs CLI ​

The published Python API is focused on evaluation runs: worldjen.config, worldjen.Dimensions, and worldjen.run() (which creates a local SDK-style run, runs your pipeline on this machine, uploads videos, and optionally waits for evals). That does not use a worker queue for generation.

worldjen.runs.create(...) requires runner_id and model_id and enqueues a run like the web UI. For advanced cases (e.g. tooling that only creates a run record without a queue), the lower-level worldjen._api.create_run can omit a runner.

Everything the CLI does against the HTTP API lives in the internal module worldjen._api (not part of the stable public surface). Runner install/start/stop/status/logs and systemd integration are CLI-only on the machine where the worker runs.

For full CLI options run worldjen --help, worldjen runs create --help, worldjen runs --help, and similarly for models, runner, etc.