Python SDK

The WorldJen Python SDK is the programmatic surface for local evaluation runs and resource management. Use it when you want typed Python helpers instead of shell commands or raw HTTP.

Install

Install the core package:

pip install worldjen

With uv:

uv pip install worldjen

Install the runner extra only on machines that should operate the GPU runner:

pip install "worldjen[runner]"

Configure

Set your API key in the environment:

export WORLDJEN_API_KEY="wjk_..."

Or configure it in Python:

import worldjen

worldjen.config(api_key="wjk_...")

Local pipeline runs

Use worldjen.run() when your generation code already runs in Python. The SDK creates a run, calls your pipeline locally, uploads generated media, and can wait for evaluation results.

import worldjen

result = worldjen.run(
    my_pipeline,
    dimensions=[worldjen.Dimensions.SUBJECT_CONSISTENCY],
    run_name="ltx2-motion-check",
    model_id="my-org/my-model",
    wait_for_evals=True,
    reasoning_enabled=True,
)

print(result.run_id, result.status, result.eval_results)

Your pipeline can be a callable or an object with generate or infer. It should accept a prompt and return media frames or files that the SDK can upload. Reasoning and generated summaries are off by default; pass reasoning_enabled=True to store them.

Dimensions

Use the Dimensions enum for stable IDs:

from worldjen import Dimensions

video_dimensions = [
    Dimensions.SUBJECT_CONSISTENCY,
    Dimensions.MOTION_SMOOTHNESS,
    Dimensions.SEMANTIC_ADHERENCE,
]

You can also fetch server-side dimension metadata:

import worldjen

all_dimensions = worldjen.list_dimensions()
image_dimensions = worldjen.list_dimensions(model_type="t2i")

See Dimensions for descriptions.

Queued runs

Use worldjen.runs.create(...) when you want the same worker-queue flow as the dashboard. This requires a runner ID and model ID.

import worldjen

run_id = worldjen.runs.create(
    name="nightly-comparison",
    dimensions=["subject_consistency", "motion_smoothness"],
    runner_id="RUNNER_ID",
    model_id="MODEL_ID",
    reference_model_id="REFERENCE_MODEL_ID",
    reasoning_enabled=True,
)

final = worldjen.runs.wait(run_id, poll_interval=2, timeout=600)
print(final["status"])

Run helpers:

Function	Purpose
worldjen.runs.list_runs(status=None, page=1, limit=50)	List runs
worldjen.runs.get(run_id)	Fetch run metadata and progress
worldjen.runs.wait(run_id)	Poll until the run is terminal
worldjen.runs.cancel(run_id)	Cancel a run
worldjen.runs.delete(run_id)	Delete a run
worldjen.runs.get_logs(run_id)	Fetch run logs
worldjen.runs.get_csv(run_id)	Download CSV bytes
worldjen.runs.get_videos(run_id)	List generated media
worldjen.runs.download_videos(run_id, output_dir=".")	Download generated media

Models

import worldjen

models = worldjen.models.list_user()
base_models = worldjen.models.list_base()
reference_models = worldjen.models.list_ref()

created = worldjen.models.create(
    name="LTX-2",
    provider="huggingface",
    hf_repo_id="Lightricks/LTX-2",
    model_type="text_to_video",
)

worldjen.models.delete(created["_id"])

For private Hugging Face repos, configure credentials in the dashboard or pass encrypted runner tokens from your own tooling.

Projects and preferences

import worldjen

projects = worldjen.projects.list_projects()
project = worldjen.projects.get("PROJECT_ID")

prefs = worldjen.preferences.get()
worldjen.preferences.set_notifications(True)
worldjen.preferences.set_cache_i2v_images(False)

API keys

The SDK can list API keys. Create and revoke keys in the dashboard to keep high-impact credential operations interactive.

import worldjen

keys = worldjen.api_keys.list_keys()

SDK vs CLI

Use the SDK for Python-native automation and local pipeline execution. Use the CLI for shell scripts, runner service operations, and one-off inspection. Both wrap the same REST API.