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. Use the Agent API, DreamLayer CLI, or Image Agent MCP Server. An App Sprite Sheets page and App billing are not included in this release.

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 sprite_pricing in capabilities

Animation options

Option	What to send
`animation_prompt`	A nonblank instruction of 1–4000 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.

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. Frames 1–14 cost

0.14 each; every additional frame costs

0.07. There is no separate generation fee. One credit is

0.17. Divide the total price by

0.17, then round upward once to one decimal credit. Seven frames cost 5.8 credits, fourteen cost 11.6, fifteen cost 12, and one hundred cost 47. Displayed balances round down to one decimal without changing stored funds. Quotes round credits, not dollars, once per complete order:

Frames	Tier subtotal	Credits before rounding	Final credit quote	Exact USD value of debited credits
7	$0.98	98/17 = 5.764705…	5.8	$0.986
14	$1.96	196/17 = 11.529411…	11.6	$1.972
15	$2.03	203/17 = 11.941176…	12.0	$2.040
100	$7.98	798/17 = 46.941176…	47.0	$7.990

The final credit quote is the amount held and settled. The USD column explains its value at $0.17 per credit; it is not a second dollar charge or rounding step. Compare the quote with available from balance, not the sum of separately rounded funding balances.

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.8 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.8
  }'

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.1 is published under beta; the unversioned latest release remains 0.3.0 and does not include sprites.

npx --yes dreamlayer@0.4.0-beta.1 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.

Use the published beta MCP server

Configure @dreamlayer/mcp@0.4.0-beta.1 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.”

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 transparent PNGs, each frame_size by frame_size
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.
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.1 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

Command line and agents

Project

Endpoint reference

What this lets you do

What you need

Animation options

Price and frame count

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

​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

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