Sprite sheets

What this lets you do

Describe an animation for a character, creature, object, or effect. Get one downloadable ZIP containing a transparent sprite sheet, 7–100 transparent frame PNGs, an atlas, an animated preview, and import instructions. The beta is live for all authenticated accounts, subject to normal credit and quota checks. This guide covers the Agent API, DreamLayer CLI, and Image Agent MCP Server, which share your API balance. The App Sprite Sheets page uses your separate App balance. See App sprite prices.

What you need

An API key whose GET /v1/capabilities response includes sprite_sheet
A reference image with the whole subject visible and space around it
An animation instruction or a walk, run, or idle preset
Enough credits for the selected count; read the account estimate from GET /v1/sprite-pricing

Sprite-sheet animation instructions have a 4,000-character limit. This applies to options.animation_prompt, including spaces and line breaks, not a word count. Keep one complete nonblank instruction within that limit. Longer prompts are rejected with 422; they are not automatically shortened.

Animation options

Option	What to send
`animation_prompt`	A nonblank instruction of 1 to 4,000 characters, such as a sword attack, jumping creature, spinning coin, opening chest, or flickering flame.
`action`	Optional alternative to a custom instruction: `walk`, `run`, or `idle`. Send exactly one of `action` and `animation_prompt`.
`animation_mode`	`loop` for repeating motion or `once` for a one-time action. Defaults to `loop` for presets and `once` for custom instructions.
`frame_count`	Integer from 7 to 100. Default: 12.
`frame_size`	Square canvas size: 32, 64, 128, 256, 512, 720, or 1080 pixels. Default: 512.
`background`	`remove` for transparent frames, or `keep` to deliver the frames as generated. Default: `remove`.

For a turntable, ask for a full 360-degree subject rotation with a stationary camera and choose loop. Describe the pose, viewpoint, movement, and style you want. Custom instructions do not force a walking pose or a right-facing character. The walk and run presets retain their side-view, right-facing behavior; idle retains the reference’s viewing direction. One-time animations retain their progression, including the beginning and ending. Looping animations avoid an identical closing frame; a seamless loop is not guaranteed. Frame durations in the atlas and preview preserve timing, including held poses. Requests with too few distinct frames fail with insufficient_frames and restore the held credits. Frames are never duplicated or interpolated just to reach the requested count. Export size does not change the price. Aspect ratio and shared alignment are preserved with transparent padding. Larger exports cannot recover missing source detail, and small exports are not automatically pixel art. At smaller sizes, distinct poses can become identical and cause insufficient_frames.

The frame-size response issue is fixed. All seven sizes are covered by the API’s result limits; 512 remains the default, not a required workaround. If a completed job’s result could not be displayed, retry status and download using its original execution ID. Do not regenerate or pay again just to retrieve an existing completed output.

Price and frame count

Request an integer from 7 to 100. The default is 12. Transparent sheets cost 4.2 API credits plus 0.2 per frame, including generation and exports. New public API credits cost $0.15 each. The console and GET /v1/balance?pricing=current display up to four decimal places; the legacy balance response rounds down to one decimal. Neither changes stored funds. Transparent sheet examples:

Frames	API credits	Public equivalent at $0.15 per credit
7	5.6	$0.84
12	6.6	$0.99
24	9.0	$1.35
100	24.2	$3.63

Read GET /v1/sprite-pricing?frame_count=12&background=remove with your API key for an account-specific estimate. The response has decimal-string credits, reference_usd, reference_credit_cents, price_version, and binding: false. The estimate does not reserve funds; admission checks the current price against your max_credits ceiling before any debit. Compare it with available from balance, not separately rounded funding balances. Use GET /v1/capabilities?pricing=current for the current formula. Default capabilities contain deprecated historical estimates for old-client compatibility, not today’s prices. USD equivalents are not an additional charge or a revaluation of existing credits.

When a frame will not cut out

Background removal occasionally returns an empty image for a frame, most often in fast motion where the subject is mostly blur. That frame is retried against nearby moments of the same clip, which usually cut cleanly. If none of them do, that single frame keeps its background and the sheet is still delivered, with the frame numbers listed in atlas.json as kept_background_frames so you can key them out yourself. A request fails only when more than one frame in six cannot be cut, which reports cutout_unusable_many and returns the held credits.

Keeping the background

Send "background": "keep" to skip background removal. The reference price is $0.32 plus $0.01 per frame. Divide that price by your account’s undiscounted API credit purchase rate and round upward once to four decimal credits. Public and approved-agency accounts have the same reference dollar target, but their credit quantities can differ. Purchase discounts remain savings.

Frames	Public API credits	Reference USD
7	2.6	$0.39
12	2.9334	$0.44
100	8.8	$1.32

Use it when the reference already sits on a background you want, when a fast motion makes removal unreliable, or when your engine handles keying itself. The frames keep whatever background the animation produced, so they are not drop-in game sprites.

Steps

1. Upload a reference

Set DREAMLAYER_API_KEY locally, then upload a PNG, JPEG, or WebP reference under 20 MiB:

curl --fail-with-body https://api.dreamlayer.io/v1/input-assets \
  -H "Authorization: Bearer $DREAMLAYER_API_KEY" \
  -F 'file=@./character.png'

2. Authorize and submit the animation

Use the returned input_asset_id below. This starts a real, billable job with an approved limit of 5.6 API credits:

curl --fail-with-body https://api.dreamlayer.io/v1/execute \
  -H "Authorization: Bearer $DREAMLAYER_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'DreamLayer-Version: 1' \
  -H 'Idempotency-Key: turntable-001' \
  -d '{
    "operation": "sprite_sheet",
    "input_asset_id": "REPLACE_WITH_UPLOADED_ASSET_ID",
    "options": {
      "animation_prompt": "Rotate this character through a full 360-degree turn, keeping the pose fixed and camera stationary. Keep the entire subject visible.",
      "animation_mode": "loop",
      "frame_count": 7,
      "frame_size": 512
    },
    "max_credits": 5.6
  }'

For a preset, replace options with:

{
  "action": "walk",
  "frame_count": 7,
  "frame_size": 512
}

Put custom instructions in options.animation_prompt, not the top-level image prompt. Do not combine a preset and a custom instruction. Set max_credits to your approved limit after checking the current price. Credits are held when the request starts, charged when the complete sheet is delivered, and returned if generation fails or times out. Sprite requests have no customer cancellation. An identical replay with the same idempotency key keeps the original price.

3. Follow progress and download

Jobs can take several minutes. A stream ending does not mean the job failed. Save the execution ID and resume events with Last-Event-ID, or read GET /v1/executions/{execution_id}. When complete, authenticate the returned download URL and save the ZIP. Reconnect to the same execution instead of starting another job after an uncertain response.

Use the published beta CLI

Requires Node.js 22.12 or later and DREAMLAYER_API_KEY. Version 0.4.0-beta.4 is published under beta; the unversioned latest release remains 0.3.0 and does not include sprites. Keeping the background needs 0.4.0-beta.4 or later, because earlier builds had no flag for it.

npx --yes dreamlayer@0.4.0-beta.4 sprite ./character.png \
  --animation-prompt 'Rotate this character through a full 360-degree turn with a fixed pose and stationary camera.' \
  --animation-mode loop --frames 7 --frame-size 512 \
  --max-credits 5.8 --out ./turntable.zip

For a preset, replace --animation-prompt ... with --action walk, --action run, or --action idle. The CLI defaults to walk if neither is supplied; direct API requests must supply one. The published beta still checks a historical local estimate. The 5.8-credit ceiling above accommodates that check; the new seven-frame transparent request costs 5.6 credits. A ceiling is permission to spend up to an amount, not an extra charge. Read the authenticated current estimate before approving a request. No newer client release is required to receive the server’s lower price.

Use the published beta MCP server

Configure @dreamlayer/mcp@0.4.0-beta.5 using the MCP setup guide. Call dreamlayer_upload_image, then dreamlayer_generate with the same sprite request options and approved max_credits. Active results include an execution ID and continuation instructions. Use dreamlayer_events until terminal, then dreamlayer_download with the execution ID and an absolute output path. For example, ask your connected assistant: “Make a 7-frame, 512-pixel looping turntable from this reference. Rotate the subject through 360 degrees with a fixed pose and stationary camera. I authorize at most 5.8 API credits. Save the ZIP as turntable.zip.” As with the pinned CLI, this older MCP version uses historical local validation. The approved 5.8-credit ceiling accommodates it; a new seven-frame transparent request costs 5.6 credits. Always approve the actual requested ceiling before a billable call.

Confirm it worked

The finished asset has content_type: application/zip. Inside it:

sheet.png: a grid of cells at your selected frame size
frames/: the requested count of aligned PNGs, each frame_size by frame_size, transparent unless you sent "background": "keep"
atlas.json: frame rectangles, cell, alignment, enlarged, duration_ms, frame_durations_ms, and cycle or sequence information
preview.gif: animation preview
README.txt: engine import instructions

Each atlas rectangle reconstructs its corresponding PNG exactly. Review the preview for motion and character consistency before importing into your game.

Beta limitations

Broad requests are supported, not guaranteed results. Fine details may change, accessories or subjects can leave the frame, and a front-only reference requires unseen back and side details to be invented. Turntables are valid requests, but exact consistency is not guaranteed. Transparent PNG output preserves partial alpha and disconnected elements where present. Effects such as smoke, sparks, and flames can still lose detail or transparency. Inspect the output; do not assume every effect can be separated cleanly from its background. All 658 frame-count/size combinations passed local HTTP result tests with mocked database and storage. The 100-frame, 1080-pixel combination also passed synthetic export tests, and the public API’s result limits cover its 10800-pixel sheet. These tests do not establish live animation quality. Fresh live broad-animation quality and 100-frame completion time and cost have not been verified. Publication checks covered installation, startup, and read-only access, not a new end-to-end production sprite job. Submission, queue delivery, generation, authenticated ZIP download, and exact credit settlement have not been validated together in production.

Common errors

422: check the reference, exactly one preset or custom instruction, frame count, frame size, animation mode, and credit limit.
Prompt too long: shorten options.animation_prompt to 4,000 characters or fewer, including spaces and line breaks. Do not split one intended animation into separate paid jobs just to bypass the limit.
402: add enough credits for the complete job.
404: use an asset owned by the authenticated account.
Failed output: the reserved credits are restored. Check your reference before submitting a new job.
insufficient_frames: too few distinct output frames. Review the request before trying fewer frames or a larger frame size. A new submission is a new billable attempt if successful.

Troubleshooting

Use npx --yes dreamlayer@0.4.0-beta.4 status EXECUTION_ID to inspect existing work. Reconnect to an existing execution instead of submitting a second job when a connection closes.

Start

DreamLayer Agent API

Video

Command line and agents

Project

Endpoint reference

What this lets you do

What you need

Animation options

Price and frame count

When a frame will not cut out

Keeping the background

Steps

1. Upload a reference

2. Authorize and submit the animation

3. Follow progress and download

Use the published beta CLI

Use the published beta MCP server

Confirm it worked

Beta limitations

Common errors

Troubleshooting

Next steps

​What this lets you do

​What you need

​Animation options

​Price and frame count

​When a frame will not cut out

​Keeping the background

​Steps

​1. Upload a reference

​2. Authorize and submit the animation

​3. Follow progress and download

​Use the published beta CLI

​Use the published beta MCP server

​Confirm it worked

​Beta limitations

​Common errors

​Troubleshooting

​Next steps

What this lets you do

What you need

Animation options

Price and frame count

When a frame will not cut out

Keeping the background

Steps

1. Upload a reference

2. Authorize and submit the animation

3. Follow progress and download

Use the published beta CLI

Use the published beta MCP server

Confirm it worked

Beta limitations

Common errors

Troubleshooting

Next steps