> ## 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, sprite, and video API authentication, quotes, execution, streaming, and recovery.

DreamLayer generates images, sprite sheets, and videos 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, conversation, and Video endpoints. 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 |
| `text_to_video` (quote first) | Prompt, supported settings, then accepted `quote_id` | MP4, sound on by default |
| `image_to_video` (quote first) | Prompt and one reference, then accepted `quote_id` | MP4, source-driven aspect |

Read `GET /v1/capabilities` for account operation availability. For current account-specific sprite pricing, use authenticated `GET /v1/sprite-pricing` with the frame count and background mode; default capabilities pricing is historical compatibility data. Sprite sheets are beta. Image operations cost one credit on successful delivery. Sprites reserve their approved charge and settle on complete delivery; failure or timeout restores the hold. Read `GET /v1/balance?pricing=current` for available credits before paid work. The sprite estimate is non-binding and never authorizes generation by itself.

For Video, use `GET /v1/video/capabilities` separately. Create `POST /v1/video/quotes`, review the settings and credit amount, then send only `quote_id` and `max_credits` to `/v1/execute` with a stable idempotency key. Do not send the Video operation directly as an image execution body. See [Video quickstart](/agent-api/text-to-video).

## Start and follow an image or sprite 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. Images/sprites permit two active jobs per account and four open streams per key. Video has a separate two-job allowance and three-stream limit, also subject to shared service capacity. 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`.

For images and sprites, 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.

Video acceptance instead returns `202` JSON after admission, or an immediate error such as `402 insufficient_credits`, `409 quote_expired`, or `429 too_many_active_jobs`. Follow its `video_job`, use the [Video states and events](/agent-api/video-jobs), and download from `/v1/video/executions/{execution_id}/asset`. Image status enums and initial SSE behavior do not apply to Video.

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
* [Video guides](/agent-api/video), including sound, settings, billing, and cancellation
* [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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.