> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dreamlayer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Use typed local and managed image clients from Python.

# Python SDK

## What this lets you do

Create durable image turns from Python against a local runtime or DreamLayer Agent API.

## What you need

* Python 3.11 or later
* A DreamLayer clone for local installation
* A running local runtime or a server-side `DREAMLAYER_API_KEY`

## Steps

### 1. Install from the clone

```bash theme={null}
uv pip install ./packages/python-sdk
```

### 2. Create a local conversation

```python theme={null}
from pathlib import Path

from dreamlayer import RuntimeClient
from dreamlayer.models import CreateJobRequest

token = (
    Path.home()
    .joinpath(".dreamlayer-runtime/runtime-token")
    .read_text(encoding="utf-8")
    .strip()
)

with RuntimeClient(runtime_token=token) as client:
    accepted = client.create_conversation(
        CreateJobRequest(
            client_request_id=client.operation_id(),
            prompt="A glass greenhouse at dusk",
        )
    )
    for job in client.watch_job(accepted.job.job_id):
        print(job.stage)
```

### 3. Create a managed execution

```python theme={null}
import os
from dreamlayer import ManagedClient

with ManagedClient(api_key=os.environ["DREAMLAYER_API_KEY"]) as client:
    for event in client.execute(
        prompt="A glass greenhouse at dusk",
        idempotency_key="greenhouse-001",
    ):
        print(event.event, event.data)
```

Keep managed keys in server-side environment variables.

## Confirm it worked

The local example prints durable job stages ending in a terminal state. The managed example prints an `asset` event followed by `done` with status `completed`.

## Common errors

* `401`: replace a missing, invalid, or revoked managed key.
* `402`: add live credits or use a test key.
* Connection refused: start the local runtime and use its printed loopback URL.

## Troubleshooting

Reuse the same idempotency key after an uncertain managed response. Read [Idempotency and retries](/agent-api/idempotency-and-retries) before retrying a mutation.

## Next steps

* [Create managed conversations](/agent-api/conversations)
* [Resume job events](/agent-api/jobs-and-events)
* [Build an orchestrator](/orchestrators)