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

# API reference

> DreamLayer image API authentication, operations, async execution, streaming, limits, and recovery.

DreamLayer generates and edits images through a hosted REST API. Use `https://api.dreamlayer.io`, authenticate with `Authorization: Bearer YOUR_API_KEY`, and send `DreamLayer-Version: 1` on managed execution and conversation requests. Keep keys on the server; create and revoke them in the [developer console](https://platform.dreamlayer.io).

## Operations

| Operation           | Required input                                                 | Output                                  |
| ------------------- | -------------------------------------------------------------- | --------------------------------------- |
| `text_to_image`     | Prompt; no reference asset                                     | PNG                                     |
| `image_to_image`    | Prompt and one uploaded reference                              | PNG                                     |
| `background_remove` | Prompt and one uploaded reference                              | Transparent PNG                         |
| `upscale`           | Prompt and one reference with longest side at most 2048 pixels | PNG with each side doubled              |
| `sprite_sheet`      | One reference, animation options, and approved `max_credits`   | ZIP of frames, sheet, atlas and preview |

Read `GET /v1/capabilities` for account operation availability and current sprite pricing. Sprite sheets are beta. Image operations cost one credit on successful delivery. Sprites reserve their approved quote and settle on complete delivery; failure or timeout restores the hold. Read `GET /v1/balance` for available credits before paid work.

## Start and follow an execution

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

JSON requests receive `202` with an execution ID. Persist it, then read `GET /v1/executions/{execution_id}` or follow `GET /v1/executions/{execution_id}/events`. Request `Accept: text/event-stream` on submission if you prefer an initial SSE stream.

The event set is `started`, `thinking`, `progress`, `job`, `question`, `asset`, and `done`. Resume with `Last-Event-ID`. A closed connection does not end a job. Canonical execution states are `queued`, `running`, `needs_input`, `completed`, `failed`, and `cancelled`. A completed output is downloaded through `GET /v1/image-jobs/{job_id}/asset`, using the owned `download_url` from the execution. It redirects to a signed URL valid for 15 minutes, with credentials restricted to the API origin.

## Limits and safe retries

POST requests share a 10-request window per 60 seconds; most GET requests share 120 per 60 seconds; asset downloads allow 20 per 60 seconds. Each bucket applies both per key and per account. The beta allows two active jobs per account and four open execution streams per key. See [exact scopes and handling](/agent-api/limits).

Errors include a stable `reason`, `retryable`, and `request_id`, with `X-Request-ID` on the response. `Retry-After` and remaining/reset headers are not guaranteed. Back off with jitter on `429`. A missing Authorization header returns `422`; an invalid or revoked bearer key returns `401`. A conflicting idempotency request returns `409`.

Acceptance is not admission: credit, quota, and active-job checks run after `/v1/execute` accepts the request. Non-retryable admission failures appear as `status: failed` with an `error` object on the execution and its `done` event, not as a submit-time `402`. Retryable admission failures remain queued and are retried by the service. Keep following the existing execution.

Give every logical submission its own stable idempotency key. Replay identical request bytes with that original key after uncertainty; do not re-upload a reference or create a replacement key automatically. Read known execution state first.

## Build your integration

* [OpenAPI 3.1 specification](/openapi/managed.yaml), plus generated endpoint pages in the navigation
* [Runnable Python and JavaScript clients](/agent-api/examples) with saved requests, SSE recovery and downloads
* [Multiple-image queue](/agent-api/multiple-images) with bounded concurrency and partial-failure handling
* [Event payloads](/agent-api/jobs-and-events), [errors](/agent-api/errors), and [idempotency](/agent-api/idempotency-and-retries)
* [MCP setup](/mcp/index) and [CLI guide](/cli)

This API uses asynchronous executions, SSE and status reads. A native batch endpoint and webhook delivery contract are not part of this documented interface. Use the client queue and event stream for those integration needs.