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

# DreamLayer Agent API

> Use the paid managed path for opaque image orchestration and execution.

# DreamLayer Agent API

## What this lets you do

Use one managed image API for hosted routing, execution, recovery, billing, and asset delivery. The open local paths remain free to run without it.

## What you need

* A server-side DreamLayer test or live key
* `curl`
* Protocol version `1`

## Steps

### 1. Store the key for this shell

```bash theme={null}
read -s DREAMLAYER_API_KEY
export DREAMLAYER_API_KEY
```

### 2. Send the first request

```bash theme={null}
curl --no-buffer https://api.dreamlayer.io/v1/execute \
  -H "Authorization: Bearer $DREAMLAYER_API_KEY" \
  -H "DreamLayer-Version: 1" \
  -H "Idempotency-Key: greenhouse-001" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A glass greenhouse at dusk","aspect_ratio":"1:1"}'
```

The stream may emit `started`, `thinking`, `progress`, `job`, `question`, `asset`, and `done`. `thinking` is empty operational state, not hidden reasoning.

### 3. Choose test or live mode

A test key returns a deterministic image, calls no provider, and consumes no credits. A live key reserves and settles one credit for a completed text-to-image or image-to-image operation.

## Confirm it worked

The stream begins with `started`, emits one `asset`, and ends with `done` status `completed`. Save the returned opaque execution and conversation IDs.

## Common errors

* `401`: the key is missing, invalid, or revoked.
* `402`: the live account does not have one available credit.
* `429`: the account reached a request or concurrency limit.
* `503`: managed execution is disabled.

## Troubleshooting

Do not create a new idempotency key after an uncertain response. Read [Jobs and event streams](/agent-api/jobs-and-events) and [Idempotency and retries](/agent-api/idempotency-and-retries).

## Next steps

* [Create and revoke API keys](/agent-api/api-keys)
* [Run text-to-image](/agent-api/text-to-image)
* [Upload one reference image](/agent-api/image-to-image)