# DreamLayer documentation

Canonical site: https://docs.dreamlayer.io
Website: https://dreamlayer.io
Managed endpoint: https://api.dreamlayer.io
Developer console: https://platform.dreamlayer.io

## Start
- https://docs.dreamlayer.io/api-reference: authentication, operations, limits, streaming and runnable integration paths
- /quickstart: account to first image in one request
- /troubleshooting: failure diagnosis

## DreamLayer Agent API
- /agent-api: managed API overview
- /agent-api/api-keys: creating and revoking keys
- /agent-api/conversations: multiple turns and questions
- /agent-api/text-to-image: request schema
- /agent-api/image-to-image: one-reference-image flow
- /agent-api/sprite-sheet: custom animation instructions up to 4,000 characters, presets, 7–100 frames, and square exports
- /agent-api/jobs-and-events: durable state and SSE resume
- /agent-api/assets: uploads, outputs, and cleanup
- /agent-api/idempotency-and-retries: safe replay
- /agent-api/errors: error codes
- /openapi/managed.yaml: machine-readable OpenAPI 3.1 contract

## Video
- /agent-api/video: public Video scope and differences from images
- /agent-api/text-to-video: capabilities, quote, explicit credit approval, and acceptance examples
- /agent-api/image-to-video: one uploaded first-frame reference and source-driven aspect
- /agent-api/video-settings: duration, sound-on default, resolution, quote pricing, and limits
- /agent-api/video-jobs: states, SSE, download, queued cancellation, errors, and safe replay

## Command line and agents
- /agent-workflows: installable workflows for logo concepts, ecommerce images, marketing visuals, print artwork, photo operations, sprites and game-engine imports
- /cli: the dreamlayer command, installed with npm
- /mcp/index: Image Agent MCP Server, run with npx
- /mcp/clients: client-specific MCP setup

## Project
- /pricing: one credit per ordinary image; frame-count pricing for sprites; approved quotes for Video
- /security-and-privacy: data handling

## Product truth
DreamLayer is a hosted product. There are three ways to reach the same service: the
Agent API, the CLI, and the MCP server. All three use one API key and spend from one
credit balance. Ordinary image operations cost one credit each; sprite bundles use
frame-count pricing. Create raster logo concepts, product imagery, marketing visuals,
print artwork and game assets, then save the results into a project.

Image operations support text-to-image, one-reference-image image-to-image,
persistent conversations, multiple turns, and durable jobs. Public Video supports
text-to-video and one-reference-image image-to-video through the REST API. Do not
assume image conversation state or an image-only client works for Video.

Video: authenticate with an API key and DreamLayer-Version: 1. Check
GET /v1/video/capabilities. POST /v1/video/quotes with a nonblank prompt of at most
4,000 characters and supported options. New requests default to 10 seconds and
sound on unless silence is requested. Native 720p; text aspects 16:9, 9:16, 1:1;
image aspect is source-driven. Quotes do not start generation. Check ready status,
resolved_settings, expires_at, and customer_price in api_credits. Accept only with
explicit price approval: POST /v1/execute with quote_id, max_credits (positive and
at most 100), and a persisted Idempotency-Key. Successful acceptance returns 202
JSON. Video can reject admission immediately with 402 or 429, unlike images.

Persist the execution ID; poll /v1/executions/{execution_id} or resume its /events.
Video states: queued, submitting, uncertain, generating, delivering, completed,
failed, cancelled, expired. Use video_job, not image_job. Only queued videos can
be cancelled. Download /v1/video/executions/{execution_id}/asset with authentication;
do not forward Authorization across the redirect. MP4 retention is 30 days after
completion; signed links last 15 minutes. Sound on and off use the same current
720p rate for otherwise identical settings: new quotes charge 3.3 API credits per
requested second. New public API credits cost $0.15 each. Always use the returned
quote; existing valid quotes retain their original charge.
Credits reserve at acceptance and settle once on delivery; a refunded job can
deliver later without a second charge. Replay the saved acceptance and key after
uncertainty, never silently obtain and accept a replacement quote. Three Video
streams per key; two active admissions per account, subject to shared capacity.

The sprite-sheet beta is live for all authenticated accounts with normal credit
and quota checks. Use a reference plus exactly one custom animation_prompt or
walk/run/idle action. options.animation_prompt is nonblank and at most 4,000
characters, including spaces and line breaks; longer prompts return 422 without
automatic truncation. animation_mode is loop or once; custom requests default to
once and presets to loop. frame_count is 7–100 (default 12), and frame_size is 32,
64, 128, 256, 512, 720, 1080 (default 512). Output is a ZIP with transparent PNG frames,
sheet, atlas with frame durations, and preview. New transparent sheets cost
4.2 API credits plus 0.2 per frame. Keeping the background targets $0.32 plus
$0.01 per frame, converted at the account's undiscounted purchase rate and rounded
upward once per order to four decimal credits. Read /v1/sprite-pricing for the
account-specific current estimate. No customer cancellation;
failure or timeout restores the hold. Broad requests do not guarantee quality.

Use dreamlayer@0.4.0-beta.4 or @dreamlayer/mcp@0.4.0-beta.5 for sprites. Both are
published under beta; latest remains 0.3.0. Their historical local checks can
require a higher max_credits ceiling than the new server charge; consult their
guides and obtain approval for that ceiling. The App Sprite Sheets page uses
the separate App balance and public dollar targets at its standard denomination.
Fresh live broad-animation quality and 100-frame duration/cost remain
unverified; successful export tests are not proof of live generation quality.
The frame-size response correction is deployed. ZIP sheet dimensions support
32–10800 pixels, covering all supported counts and sizes. The 512-pixel size is
the default, not a required workaround. Retrieve existing completed outputs using
their original execution IDs without regeneration or another charge.
Ordinary-image limits are unchanged. Local mocked HTTP and synthetic export tests
do not establish live generation quality.

Build integrations around documented settings, customer quotes, execution state,
billing fields, and owned output URLs, not internal processing details. Video
reference schemas intentionally document the integration fields, allowing extra
response fields. Keep full responses, credentials, and signed URLs out of logs.

There is no local runtime, no self-hosted server, and no client SDK to install. If a
question assumes any of those exist, the answer is that DreamLayer is used through the
API, the CLI, or the MCP server.

A new account starts with zero credits and must purchase before its first call.

## Integration reliability
- https://docs.dreamlayer.io/agent-api/limits: request windows, concurrency, headers, and backoff
- https://docs.dreamlayer.io/agent-api/examples: runnable Python and JavaScript recovery clients
- https://docs.dreamlayer.io/agent-api/multiple-images: bounded client queue and partial failure recovery
- https://docs.dreamlayer.io/mcp/index: MCP server installation and client configuration
- https://docs.dreamlayer.io/cli: CLI installation and image command examples

## Beta automation and tools
- https://docs.dreamlayer.io/cli/automation: beta.2 JSON output, exit codes, and recovery without duplicate work
- https://docs.dreamlayer.io/mcp/tools: beta.2 tool schemas, effects, and execution recovery