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):

pip install worldjen

With uv:

uv pip install worldjen

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

pip install "worldjen[runner]"

With uv, activate a virtual environment first:

uv venv && source .venv/bin/activate
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.

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.

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). Pass --reference-model-id to compare against another model in the same run (the dashboard's reference-model flow).

• worldjen runs create --name NAME --dimensions DIM1,DIM2 --runner-id RUNNER_ID --model-id MODEL_ID [--run-instructions JSON_OR_PATH] [--reference-model-id REF_MODEL_ID]
• 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

Playground & Rank

The Playground and Rank surfaces in the dashboard are user-scoped sandbox runs (one of each per user) for ad-hoc custom-prompt evaluations. The CLI mirrors the dashboard's reset/get behavior; pass --kind rank to target Rank.

• worldjen playground get [--kind playground|rank] — fetch (or lazily create) the active sandbox run
• worldjen playground reset [--kind playground|rank] — clear all videos from the active sandbox run (run id is preserved)

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.

Multi-runner on one machine: every runner subcommand takes --name INSTANCE (default default). Each instance has its own config (runner-{name}.conf), key file, and systemd service (worldjen-runner@{name}), so a single host can run multiple runners side-by-side sharing one venv and model cache. Pass the same --name to every subcommand that targets a given instance.

• Backend: worldjen runner create [--name INSTANCE] [--display-name "Human Name"] — create runner, register this machine, install and start service. --name is the local instance id (used for the config file and systemd unit); --display-name is the human-friendly label shown in the dashboard (defaults to --name).
• Backend: worldjen runner delete [--name INSTANCE] [--runner-id ID] — delete runner from account and uninstall local service
• Backend: worldjen runner list — list your runners. Add --local to list locally registered instances on this machine instead.
• Local: worldjen runner register --token TOKEN [--name INSTANCE] — register this machine with a token from the web UI
• Local: worldjen runner install [--name INSTANCE] / start [--name INSTANCE] / stop [--name INSTANCE] / status [--name INSTANCE] (systemd) / uninstall [--name INSTANCE] / logs [--name INSTANCE]

Instance names must match [a-zA-Z0-9][a-zA-Z0-9_-]{0,63} (alphanumeric, hyphens, underscores; max 64 chars; must start with alphanumeric).

worldjen runner delete removes the runner in the API, stops and uninstalls the local systemd unit, and deletes local runner-{name}.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.

Run worldjen --version (or -V) to print the installed SDK version.

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.

REST API examples (curl)

The SDK and CLI both wrap the same REST API. Use these curl snippets directly from agents, scripts, or any language without a SDK. Set WORLDJEN_API_KEY and WORLDJEN_API_URL (defaults to the production URL) first.

export WORLDJEN_API_KEY="wjk_..."
export WORLDJEN_API_URL="https://www.worldjen.com"

Create a run

Pass Idempotency-Key so retries from a flaky network don't double-create the run.

curl -sS -X POST "$WORLDJEN_API_URL/api/v1/runs" \
  -H "X-API-Key: $WORLDJEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "demo-run",
    "dimensions": ["subject_consistency", "motion_smoothness"],
    "model_id": "my-org/my-model"
  }'

List runs / get a single run

curl -sS "$WORLDJEN_API_URL/api/v1/runs?limit=20" \
  -H "X-API-Key: $WORLDJEN_API_KEY"

curl -sS "$WORLDJEN_API_URL/api/v1/runs/RUN_ID" \
  -H "X-API-Key: $WORLDJEN_API_KEY"

Cancel / delete a run

curl -sS -X POST "$WORLDJEN_API_URL/api/v1/runs/RUN_ID/cancel" \
  -H "X-API-Key: $WORLDJEN_API_KEY"

curl -sS -X DELETE "$WORLDJEN_API_URL/api/v1/runs/RUN_ID" \
  -H "X-API-Key: $WORLDJEN_API_KEY"

Dimensions, models, projects, preferences

curl -sS "$WORLDJEN_API_URL/api/v1/dimensions" -H "X-API-Key: $WORLDJEN_API_KEY"
curl -sS "$WORLDJEN_API_URL/api/v1/models"     -H "X-API-Key: $WORLDJEN_API_KEY"
curl -sS "$WORLDJEN_API_URL/api/v1/projects"   -H "X-API-Key: $WORLDJEN_API_KEY"

curl -sS -X PUT "$WORLDJEN_API_URL/api/v1/preferences" \
  -H "X-API-Key: $WORLDJEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notifications_enabled": true}'

Public leaderboard (no auth)

curl -sS "$WORLDJEN_API_URL/api/v1/public/leaderboard"

Error shape

Every HTTP error response includes a stable code so callers can branch on the failure type without parsing prose:

{
  "code": "validation_failed",
  "detail": "notifications_enabled must be a boolean"
}

Codes: validation_failed, invalid_field, unauthorized, forbidden, not_found, conflict, idempotency_mismatch, internal_error, upstream_unavailable.

SSE payloads sent inside an open /runs/:run_id/logs/stream connection use a different shape (data: { error, logs, status }) since they're event-stream messages, not REST error responses.

Rate limits

The server does not currently enforce per-key or per-IP rate limits. Agents and SDK clients should self-throttle (a few requests per second is plenty for normal use) and back off on 5xx responses. Hard limits will return in a future release.