> ## 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.

# Runnable API examples

> Python and JavaScript clients with durable request identity, SSE recovery, and authenticated downloads.

## What this lets you do

Submit an image request, preserve its identity, follow events, and recover its output without submitting replacement work. The Python and JavaScript examples use standard libraries and make the same HTTP requests.

## What you need

* Python 3.10+ or Node.js 22.12+
* A server-side `DREAMLAYER_API_KEY` and sufficient credits for generation
* [Python example](/examples/agent_client.py) or [JavaScript example](/examples/agent-client.mjs), saved locally

Capabilities, balance, and existing execution reads do not start paid generation. Submitting an image or sprite request can spend credits. The local journal contains request data and execution identifiers; keep it private and out of source control.

## Steps

### 1. Save a request

Create `request.json` for a first image:

```json theme={null}
{"operation":"text_to_image","prompt":"A glass greenhouse at dusk","aspect_ratio":"1:1"}
```

For a reference edit, [upload the image](/agent-api/image-to-image) once and save the returned input asset ID:

```json theme={null}
{"operation":"image_to_image","prompt":"Make the jacket blue","input_asset_id":"d34db33f-0000-4000-8000-000000000002"}
```

For a sprite, first confirm `sprite_sheet` and `sprite_pricing` in capabilities. Set `max_credits` to a quote you approve:

```json theme={null}
{"operation":"sprite_sheet","input_asset_id":"d34db33f-0000-4000-8000-000000000002","options":{"animation_prompt":"The subject jumps once and lands in its starting pose.","animation_mode":"once","frame_count":7,"frame_size":512},"max_credits":5.8}
```

### 2. Submit and follow

```bash theme={null}
python3 agent_client.py submit request.json job.json
node agent-client.mjs submit request.json job.json
```

The example creates `job.json` with a random idempotency key and the serialized request **before** sending the request. It asks for a JSON acknowledgement, saves the execution ID, then reads the event stream. It persists the cursor after parsing each event and checks canonical state after every connection closes.

### 3. Recover after interruption

```bash theme={null}
python3 agent_client.py resume job.json
node agent-client.mjs resume job.json
```

If an execution ID is present, recovery makes only reads. If the acknowledgement was lost, it replays the stored request bytes with the same key. The example never generates a replacement key during recovery. Do not run two processes with the same journal.

### 4. Download the existing result

```bash theme={null}
python3 agent_client.py download job.json image.png
node agent-client.mjs download job.json image.png
```

Choose `.zip` for a sprite. Downloading does not regenerate the output. The examples authenticate only to the API origin, strip credentials from redirected storage requests, and refuse to overwrite an existing destination.

## Confirm it worked

The final JSON reports `completed`, the journal retains the execution ID, and the download writes the existing PNG or ZIP. A local waiting deadline or network error leaves the journal intact for a later `resume`.

## Common errors

* `needs_input`: read `question`, answer through the conversation API, and track the answer's new execution ID.
* `failed` or `cancelled`: inspect the public error; do not automatically submit a replacement.
* `429`: back off according to [limits](/agent-api/limits). The examples stop on HTTP errors so your caller can apply its own bounded retry policy.
* An existing journal with a different request is refused. Use a new journal only for intentionally new work.

## Troubleshooting

A stream closing is not proof of completion. Only canonical state tells you whether the job is still running. These examples wait for at most 20 connections per invocation, with a pause between reads; resume later if the execution remains active. Local mock tests verify recovery, not live generation quality.

## Next steps

* [Event payloads](/agent-api/jobs-and-events)
* [Process several images](/agent-api/multiple-images)
* [Automate with CLI JSON output and recovery](/cli/automation)