Image generation and editing tools for MCP-compatible AI clients, backed by the DreamLayer Agent API.
This working tree includes the unpublished 0.5.0-beta.0 video candidate.
The published version in the installation section below remains image/sprite-only.
For local review use Node >=22.12, pnpm install --frozen-lockfile, pnpm build,
and configure the MCP client to run node /absolute/path/to/dist/index.js with an
authorized video-enabled API endpoint. This does not publish or deploy anything.
dreamlayer_video_quote performs no paid generation. dreamlayer_video_execute
admits only a ready owned quote under an explicit user-authorized credit ceiling.
Never invent that authorization. Save the idempotency key before execution.
{"tool":"dreamlayer_video_quote","arguments":{"operation":"text_to_video","prompt":"A silent forest video","options":{"resolution":"720p","generate_audio":false,"aspect_ratio":"16:9"}}}For an image, first use dreamlayer_upload_image with an absolute local path,
then use the returned owned asset ID:
{"tool":"dreamlayer_video_quote","arguments":{"operation":"image_to_video","prompt":"Restrained product showcase on a clean white background","input_asset_id":"OWNED_ASSET_UUID","context":{"use_case":"product_showcase","requested_background":"clean_white"},"options":{"model":"auto","duration_seconds":15,"generate_audio":false}}}
{"tool":"dreamlayer_video_execute","arguments":{"quote_id":"READY_QUOTE_UUID","max_credits":40,"idempotency_key":"SAVED_UNIQUE_KEY"}}
{"tool":"dreamlayer_execution","arguments":{"execution_id":"EXECUTION_UUID"}}
{"tool":"dreamlayer_events","arguments":{"execution_id":"EXECUTION_UUID"}}
{"tool":"dreamlayer_download","arguments":{"execution_id":"EXECUTION_UUID","path":"/absolute/new/result.mp4"}}The execute result includes video_job, not an inline/base64 video. Status and
events are read-only and never start work. Progress is actual execution stages,
not an invented percentage. A bounded wait or lost response does not cancel a
job; recover its identity with the same quote/key. Already consumed quotes remain
recoverable after expiry. Retry downloads without generating again.
Default: 10s when absent from both prompt and options, native 720p, no audio unless requested; text aspect 16:9. Explicit durations and issued quotes are unchanged. One image uses native/source-driven aspect. Explicit incompatible settings and extra images are rejected before charging.
Policy video-v3-scoped-intent-10s-20261010 applies only to new quotes.
Explicit compatible model first; automatic 4s or 21–30s selects Seedance.
Complex action, demanding audio, continuity, white/unknown product backgrounds
and uncertain classification prefer Seedance. Clearly simple non-white product,
one-speaker talking-head, retro or controlled cinematic-lighting scenes prefer
FLUX. Complexity beats style; these are preferences, not quality guarantees.
FLUX accepts 5–20s; Seedance 4–30s. Source pixels are not analyzed.
Spoken dialogue enables unspecified audio; captions/labels do not. Speech instructions
are not discarded by a preceding "no music" clause. Non-white is not also white;
a speaker alone does not establish simple action. Shot timestamps
are not duration/aspect settings. Overlong timelines fail before spending rather
than being compressed; dialogue is never truncated. Live-test defaults remain 5s.
Existing quotes retain their model, prompt, settings and price.
No automatic cross-provider retry, fidelity scoring, UI change, extension,
upscaling, keyframes or multiple-reference support is included. Downloads use
owned 30-day storage, bounded streaming, SHA-256 verification and no overwrite.
pricing_pending/disabled access must be reported honestly, not bypassed.
Use it for raster logo concepts, product imagery, marketing visuals, print artwork concepts and game assets. Inspect output quality and task-specific requirements. See the installable agent workflows for task guidance and Godot/Unity import examples.
The full workflow below uses the published sprite-capable beta. Stable latest
remains 0.3.0; use the explicit version shown here.
Add it to your client. Claude Code:
claude mcp add dreamlayer --env DREAMLAYER_API_KEY=dlr_live_your_key -- npx -y @dreamlayer/mcp@0.4.0-beta.5Codex:
codex mcp add dreamlayer --env DREAMLAYER_API_KEY=dlr_live_your_key -- npx -y @dreamlayer/mcp@0.4.0-beta.5Cursor, or any other stdio MCP client:
{
"mcpServers": {
"dreamlayer": {
"command": "npx",
"args": ["-y", "@dreamlayer/mcp@0.4.0-beta.5"],
"env": { "DREAMLAYER_API_KEY": "dlr_live_your_key" }
}
}
}The key must be in the server's own environment. MCP clients spawn this as a subprocess, so a key exported in your shell does not reach it. That is the most common setup failure, and the server exits with an explanation rather than starting up broken.
Get a key at platform.dreamlayer.io. A new account starts at zero credits. Ordinary image operations cost one credit each; sprite bundles use the frame-count quote described below.
| Tool | What it does |
|---|---|
dreamlayer_capabilities |
Read the contract and the operations this key may run. Spends nothing. |
dreamlayer_balance |
Read this API key's promotional, purchased, and total available credits. Spends nothing. |
dreamlayer_upload_image |
Upload PNG, JPEG, WebP, or camera RAW (up to 200 MB) and get an input_asset_id. |
dreamlayer_generate |
Generate or edit. Returns the event stream. |
dreamlayer_execution |
Read canonical state for one execution. |
dreamlayer_events |
Resume a stream after a drop, from a last event id. |
dreamlayer_download |
Save a completed execution to a new local path without generating again. |
Omit operation and DreamLayer reads the prompt, which may come back asking a
clarifying question. Name it and that inference is skipped entirely.
operation |
Needs an image | Result |
|---|---|---|
text_to_image |
No | A new image from the prompt |
image_to_image |
Yes | The reference, edited as described |
background_remove |
Yes | The subject on transparency |
upscale |
Yes | Twice the width and height |
upscale doubles each side and finished images are capped at 4096 per side, so the
longest side of your input must be 2048 or less. A larger one is refused before it
costs a credit.
A question is not a failure. An ambiguous prompt returns a question event ending
in needs_input. Answer it by calling dreamlayer_generate again with respond and
the conversation_id.
Retries are safe if you reuse the key. An idempotency_key is generated for you.
Pass the same one back to retry after an uncertain response and the original result
replays rather than paying twice.
Long runs are truncated, not lost. A stream over 256 events returns what it has,
marks truncated, and gives you the execution_id and last event id to resume from.
Errors are stable and provider-neutral. Error tool results include code, reason,
message, retryable, and request_id, matching REST and the CLI. A model should branch
on reason and retryable, never message text. The response excludes prompts, local
filenames, asset URLs, provider details, credentials, and raw upstream responses.
Node.js 22.12 or later.
MIT. See LICENSE and NOTICE.
Sprite requests accept exactly one of options.animation_prompt (1–4000 characters) or an options.action preset (walk, run, idle). Custom prompts can describe characters, creatures, objects, effects or 360° turntables. animation_mode is loop or once; presets default to loop, custom prompts to once. For a turntable, request a stationary camera and rotating subject. Broad requests do not guarantee correct motion, unseen details or successful effect transparency.
Request integer frame_count 7–100 (default 12) and frame_size 32, 64, 128, 256, 512, 720 or 1080 (default 512). These are square export canvases; a larger export does not guarantee additional detail. Aspect ratio and shared alignment are preserved with transparent padding. A bundle contains transparent PNG frames, sheet, atlas, preview and import instructions, including each frame's playback duration. Send background: "keep" in options when transparency is not needed: the frames ship with the generated background in place, plain rather than cut out, and cost the flat plain rate. A frame that cannot be cut out is retried at nearby moments of the same clip, and a single stubborn frame ships with its background rather than failing the sheet; atlas.json lists any such frame in kept_background_frames. Choose a repeating loop or a one-time action with a beginning and ending. If the requested number of distinct frames cannot be delivered, the job fails and held credits are returned. Translucent effects can lose detail or fail; small exports are not automatically pixel art.
Pricing is unchanged across sizes: frames 1–14 cost $0.14 each; additional frames $0.07 each. With background: "keep" every frame is a flat $0.07 with no tier, roughly half a transparent sheet (12 frames: 5.0 credits instead of 9.9). One credit is $0.17. Round the complete order upward once to a tenth of a credit. Check sprite_pricing in capabilities and approve the quote with max_credits. Credits are held during processing, settled after complete delivery and restored on failure/timeout. There is no customer cancellation. Keep the execution ID to resume status. Custom requests need the matching broad-animation server release; older servers reject them. New live generation quality, 100-frame duration and actual cost remain unverified.
Call dreamlayer_upload_image, then dreamlayer_generate with operation: "sprite_sheet", the uploaded input_asset_id, options: {action: "walk", frame_count: 12}, and max_credits set to your approved limit.
Each tool call waits for a bounded interval. If the result remains active, pass its execution_id and last_event_id to dreamlayer_events. When completed, use dreamlayer_download with execution_id and an absolute path ending in .zip. Existing files are never overwritten.
For affordability, compare the complete rounded quote in credits with available. One tenth of a credit is $0.017. Promotional and purchased amounts are displayed rounded down separately, so their displayed sum can be 0.1 credit below available; stored fractions are preserved. Compare against the combined total, not that sum. The order charge rounds only once, never per frame or per tier.
Read tools/list for descriptions, input schemas, and operation availability. Read-only
calls are marked with readOnlyHint; upload, generation, and local download are not.
These annotations describe effects, not permission grants. Generation starts paid work.
Every tool returns structuredContent plus the same JSON serialized in a text block for
older clients. Failures set isError: true. Generation results and errors include the
idempotency key, including when the server generated it for you. Choose and save your own
key before calling when you need recovery even after the MCP process itself is lost.
After interruption, call dreamlayer_execution with the saved execution ID, then
dreamlayer_events with the last processed event ID. Retrieve completed work with
dreamlayer_download. Never start a replacement generation merely because the stream
closed. Keep the same uploaded asset ID and identical arguments when replaying a key.
MCP setup · API overview · Execution recovery
Abrupt stream failures trigger a canonical status read. If state is still uncertain,
the error is temporarily_unavailable with recovery guidance and the known execution
ID, cursor and retry key. local_output_failed means a completed output could not be
written: fix the path and retry dreamlayer_download, not dreamlayer_generate.
Client-side input validation uses invalid_request; other unclassified client failures
use client_error and are not evidence that generation failed.
options.background selects what the frames look like. remove, the default, cuts every frame out for transparent frames. keep leaves the generated background in place: the frames are plain rather than cut out, and every frame costs the flat sprite_pricing.plain_frame_cents with no tier, about half the transparent price. Twelve frames quote 5 credits kept against 9.9 transparent.
beta.4 and earlier reject this field: their options schema set additionalProperties: false, so a request naming a background never reached the service. Pin beta.5 or later to use it.
A spelled-out background: "remove" is normalised away before the request is sent, because it is exactly what an absent field already means and the service fingerprints the options it receives; sending it would otherwise split one job into two idempotency identities.
Every input parameter in tools/list now states what it accepts, including the nested sprite options fields: prompt, conversation_id, max_credits (image operations require exactly 1; sprite jobs at or above the quoted price), aspect_ratio, execution_id and last_event_id. Tool names, arguments and results are unchanged from beta.3.
Malformed event payloads return response_contract_error with retryable: false, preserving the execution ID, last event ID and idempotency key when known. Check client compatibility or contact support; do not submit replacement work. Interrupted network streams still reconcile canonical state.