dream-engine — Python SDK for Dream Engine

dream-engine is the official Python SDK for Dream Engine, the inference engine for video world models from Dream Engines. Run frontier world models (DreamDojo · GR-1, more on the way) over HTTP with a small, typed client.

Status: v0.4.0 — stable release. Rollout, AsyncClient, typed errors, retries, predict_batch, and bundled examples are all available. See sdk/python/CHANGELOG.md for the full version history.

Install

pip install dream-engine

For mp4 → numpy frame decoding:

pip install "dream-engine[decode]"

Quickstart

import dream
import numpy as np
from PIL import Image

client = dream.Client()                              # reads DREAM_API_KEY + DREAM_BASE_URL
model  = client.models.get("dreamdojo-2b-gr1")       # ModelHandle (typed; checks the catalog)
print(model.action_dim, model.resolution)            # 384, (480, 640) — flat accessors

img  = Image.open("start.png")
acts = np.load("actions.npy")                        # (48, 384) float32

rollout = model.predict(start_frame=img, actions=acts)
print("frames:", rollout.frames, "cost:", rollout.cost_usd)
rollout.save("rollout.mp4")

# Access decoded frames as a numpy array (requires [decode] extra):
print(rollout.video().shape)  # (T, H, W, 3) uint8

You can also pass file paths or raw bytes:

# Paths (str or Path) — SDK reads the file and encodes for the wire
rollout = model.predict(start_frame="start.png", actions="actions.npy")

Set DREAM_API_KEY in your environment, or pass api_key=... to the Client(...) constructor. Mint keys at https://dreamengines.run/dashboard.

List the catalog

for handle in client.models.list():
    print(handle.slug, handle.spec.name, "active" if handle.active else "")

Visual MPC — K candidates in one server roundtrip

import numpy as np

candidates = np.random.randn(8, 48, 384).astype(np.float32)  # (K, T, action_dim)

batch = model.predict_batch(start_frame=img, actions=candidates)
print(batch.batch_size, batch.engine_wall_ms)
for r in batch.rollouts:
    print(r.cost_usd)

Wire-level access (advanced)

If you want to skip the ModelHandle layer and call the endpoint with pre-encoded bytes:

# Low-level: bypasses active-spec check and input coercion
response = client.predict(frame_bytes=frame_bytes, actions_bytes=actions_bytes)

Prefer model.predict(start_frame=…, actions=…) for most use cases. The wire-level path is for scripts that already have wire-ready bytes and don't need the typed Rollout result.

License

Apache-2.0. See LICENSE.