DreamLayer Agent API

What this lets you do

Use the Agent API for images, sprites, and quoted videos, with execution recovery, API credit billing, and owned asset delivery. Published image and sprite CLI/MCP clients use this same API and 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. For Video, check /v1/video/capabilities, create a quote, then accept its price at /v1/execute. Sound is on by default. Video always acknowledges acceptance with JSON and has its own states, synchronous admission errors, and event behavior. The image lifecycle below does not replace those rules.

Image and sprite 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.

Image and sprite 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 upward to four decimal credits, and settle on complete ZIP delivery. Failure or timeout restores the hold. Sprite requests have no customer cancellation. Video reserves its accepted quote and settles once on owned MP4 delivery. Only queued videos can be cancelled. See Video pricing and restoration. Read GET /v1/balance?pricing=current 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.
For images and sprites, nonretryable credit or quota admission failures appear after acceptance in the execution’s error object. Retryable admission failures keep the execution queued. Video instead can reject acceptance immediately with 402 or 429. Follow the operation-specific 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
Make a first video	Text-to-video
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