> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dreamlayer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Sprite sheets

> Turn a reference image and an animation instruction into a downloadable sprite sheet.

## 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](/pricing#app-sprite-prices-and-discounts).

## 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`

<Info>
  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.
</Info>

## 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`.

<Info>
  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.
</Info>

## 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](/agent-api/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:

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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.

```bash theme={null}
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](/mcp/index). 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.

## Next steps

* [Resume job events](/agent-api/jobs-and-events)
* [Download owned assets](/agent-api/assets)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.