DreamLayer Agent API

What this lets you do

Use one managed image API for routing, execution, recovery, billing, and asset delivery. The CLI and the MCP server are thin clients over this same API and the same key. For an executable first request, start with the Quickstart. This page explains the contract your integration should build around. The sprite-sheet beta is available to all authenticated accounts under normal credit and quota checks. Submit a reference image and a custom animation instruction or preset to receive a ZIP. The published CLI and MCP beta clients also support this operation. Check capabilities before selecting an operation.

Execution lifecycle

A request creates one durable execution. DreamLayer may ask a clarifying question before it starts a job. Once work begins, the execution moves through queued and running states until it completes, fails, or is cancelled. The event stream is a convenient live view, but it is not the source of truth. Save the execution_id, and read canonical state or resume the stream after a disconnect. See Jobs and event streams.

Events

The closed public event set is started, thinking, progress, job, question, asset, and done. Only done is terminal. Display text can change, so branch on event names and documented status fields instead of matching message text.

Idempotency and recovery

Give every logical request one stable Idempotency-Key. If the connection fails, inspect the saved execution or resume its events before submitting again. Reuse the same key only for the same request; a new key can create new work. See Idempotency and retries.

Billing

Image operations reserve one user credit before work begins and settle it after successful delivery. Sprite sheets instead reserve the approved frame-count quote, rounded once to a tenth of a credit, and settle on complete ZIP delivery. Failure or timeout restores the hold. Sprite requests have no customer cancellation. Read GET /v1/balance before starting work when your integration needs a current credit snapshot. The endpoint is API-key authenticated, owner-scoped, uncacheable, and makes no image request. See Check balance.

Assets

Input assets are owner-scoped and must finish server-side normalization before use. A completed execution emits an asset event with an owned download_url; follow redirects and authenticate the download. See Assets.

Common errors

422: the Authorization header is missing or the request is invalid.
401: the bearer credentials are invalid or revoked.
429: a request or event-stream limit rejected the HTTP request.
After acceptance, nonretryable credit or quota admission failures appear in a failed execution’s error object. Retryable admission failures keep the execution queued. Follow the existing execution; see error handling.
503: managed execution is disabled.

Troubleshooting

Do not create a new idempotency key after an uncertain response. Read canonical state first, and keep prompts, API keys, image data, and download URLs out of public logs.

Operation guides

Choose an integration path

You want to	Start here
Make a first image	Quickstart
Connect an AI client	MCP tool reference
Automate local files	CLI automation and recovery
Build an application	Runnable Python and JavaScript examples
Process a set of images	Bounded queue and partial recovery
Check requests and responses	OpenAPI 3.1 specification

Before paid work, read authentication, limits, and balance. Keep execution IDs and idempotency keys so stream recovery does not create duplicate work. The current integration contract uses SSE and canonical state reads. It does not document a webhook delivery contract or a native batch submission endpoint. Use the documented mechanisms rather than assuming either is available.

Start