---
title: "Adjust Sprite Sheet: re-export a previously generated sprite animation with different sheet settings - frame count, frame size, loop trimming or whitespace cropping - without generating the animation again. Free (no credits). Pass the `spritesheet_url` you received from `animateSprite`, `animateSpriteKeyframes`, `transferMotion`, `editSpritesheet`, `rotateSpritesheet` or an earlier adjust - it must be a spritesheet you generated through the API within the last 7 days; arbitrary external images are not accepted. Omit a setting to keep the source's value. The animation itself is unchanged: this only re-cuts the same video into a new sheet, so use it to fix framing (for example an effect clipped by True Size: re-export with a fixed `frame_size` or 0), to change the frame count or size for your engine, to upscale it 1.5x (`frame_size` -1), to turn loop trimming on or off, or to pack it as ordinary art when its detected pixel grid is wrong for the asset (`use_pixel_grid` false). It cannot change the motion, margins or content - use editSpritesheet for that. The source is left as it is and the result is a new spritesheet with its own `spritesheet_url`. The job result is the same sprite result as animateSprite (`spritesheet_url`, `video_url`, grid fields, optional GIF and frame URLs, and the source's `audio_url` when it has one). Limited to 20 calls per 5 minutes, 120 an hour and 1000 a day. Pass an optional request_id to tag the result for later retrieval via listGenerations (type spritesheet). Requires an API key (user scope). The call returns 202 with a job id - poll getApiJob (pass wait 30 to long-poll) honouring poll_after_ms, until status is succeeded; its result field is exactly the response documented for this operation. Synchronous responses are deprecated but still supported: pass `async: false` to block until the result is ready and receive it as the response body. Synchronous calls run on the same queue: the response carries an X-Ludo-Job-Id header, and a job still running after 15 minutes comes back as 202 with the job instead of an error. Each account may have up to 50 generations queued or running at once via the API; a request beyond that returns 429 (code PENDING_JOBS_LIMIT)."
method: POST
path: "/assets/sprite/adjust"
tags: ["Spritesheets"]
---

# Adjust Sprite Sheet: re-export a previously generated sprite animation with different sheet settings - frame count, frame size, loop trimming or whitespace cropping - without generating the animation again. Free (no credits). Pass the \`spritesheet_url\` you received from \`animateSprite\`, \`animateSpriteKeyframes\`, \`transferMotion\`, \`editSpritesheet\`, \`rotateSpritesheet\` or an earlier adjust - it must be a spritesheet you generated through the API within the last 7 days; arbitrary external images are not accepted. Omit a setting to keep the source's value. The animation itself is unchanged: this only re-cuts the same video into a new sheet, so use it to fix framing (for example an effect clipped by True Size: re-export with a fixed \`frame_size\` or 0), to change the frame count or size for your engine, to upscale it 1.5x (\`frame_size\` -1), to turn loop trimming on or off, or to pack it as ordinary art when its detected pixel grid is wrong for the asset (\`use_pixel_grid\` false). It cannot change the motion, margins or content - use editSpritesheet for that. The source is left as it is and the result is a new spritesheet with its own \`spritesheet_url\`. The job result is the same sprite result as animateSprite (\`spritesheet_url\`, \`video_url\`, grid fields, optional GIF and frame URLs, and the source's \`audio_url\` when it has one). Limited to 20 calls per 5 minutes, 120 an hour and 1000 a day. Pass an optional request_id to tag the result for later retrieval via listGenerations (type spritesheet). Requires an API key (user scope). The call returns 202 with a job id - poll getApiJob (pass wait 30 to long-poll) honouring poll_after_ms, until status is succeeded; its result field is exactly the response documented for this operation. Synchronous responses are deprecated but still supported: pass \`async: false\` to block until the result is ready and receive it as the response body. Synchronous calls run on the same queue: the response carries an X-Ludo-Job-Id header, and a job still running after 15 minutes comes back as 202 with the job instead of an error. Each account may have up to 50 generations queued or running at once via the API; a request beyond that returns 429 (code PENDING_JOBS_LIMIT).

`POST /assets/sprite/adjust`

## Request

- Base URL: `https://api.ludo.ai/api`
- URL: `https://api.ludo.ai/api/assets/sprite/adjust`
- Auth: API key in header `Authorization`

## Request body

- AdjustSpritesheetPayload: Payload for re-exporting a previously generated sprite animation with different sheet settings (Adjust Sprite Sheet in the web app).
  - `spritesheet_url` string, required: URL of a spritesheet you generated through the API in the last 7 days (the spritesheet_url returned by animateSprite, animateSpriteKeyframes, transferMotion, editSpritesheet, rotateSpritesheet or adjustSpritesheet). External URLs are not accepted.
  - `frames` 4 | 9 | 16 | 25 | 36 | 49 | 64: Number of frames in the new sheet. Omit to keep the source's frame count.
  - `frame_size` 32 | 64 | 96 | 128 | 192 | 256 | 384 | 0 | -1 | -9: Size of the sprite in pixels, not of the frame: it sets how big the character is drawn, and each frame also holds the space around it, so frames come out larger than this value. Omit to keep the source's setting. 0 is maximum resolution. -1 is AI 1.5x upscaling, which gains nothing on sources under 512 px. -9 is True Size: frames keep the size and position of the source's input image, so anything the animation adds beyond its edges is cut off - pick a fixed size or 0 to get it back.
  - `loop` boolean: Trim the animation at the beginning or end to create a seamless loop. Omit to keep the source's setting.
  - `crop` boolean: Crop frames to fit their content. Results in smaller spritesheets but inconsistent frame sizes across different animations. Omit to keep the source's setting. Ignored with True Size, which never crops.
  - `gif` boolean: When true, generates an animated GIF from the spritesheet and returns it in gif_url. Disabled by default to reduce response time.
  - `individual_frames` boolean: When true, extracts each frame from the spritesheet as an individual image and returns the URLs in individual_frame_urls.
  - `spritesheet_with_background` boolean: When true, also returns the spritesheet with background intact (before background removal). The with-background spritesheet URL will be in spritesheet_with_background_url.
  - `use_pixel_grid` boolean: Use the animation's pixel grid if one is detected. true: when Ludo detects a pixel grid with confidence, the sheet is packed on it (logical pixels, scaled up by whole blocks); when none is detected, this has no effect. false: always pack as ordinary art, for when the detected grid is wrong for your asset (for example a smooth sprite coming back as coarse blocks). Ignored for forge-pixel animations, which are always packed on their grid. Unset keeps the source spritesheet's setting (true unless it was made with false). Re-cutting with false fixes a sheet whose detected grid is wrong without generating it again.
  - `request_id` string: Optional client-provided identifier, unique per request. Re-sending the same request_id returns the existing job instead of generating again. Also usable as the request_id filter of listGenerations.
  - `async` boolean: Defaults to true: the call returns 202 immediately with a job id to poll with getApiJob. Set false for a synchronous response (deprecated but supported): the call then blocks until the result is ready.

## Response `200`

Success

- SpriteResult
  - `spritesheet_url` string
  - `video_url` string
  - `audio_url` string: URL of the sound effect generated for the animation (MP3 or WAV; the extension says which). hydra and hydra-plus only; absent for forge and forge-pixel.
  - `gif_url` string
  - `individual_frame_urls` string[]
  - `num_frames` integer: Number of frames in the spritesheet.
  - `num_cols` integer: Columns in the frame grid. Frames run left-to-right, top-to-bottom.
  - `num_rows` integer: Rows in the frame grid. The last row may be only partly filled.
  - `spritesheet_with_background_url` string
  - `individual_frame_with_background_urls` string[]
  - `duration` number, float
  - `loop` boolean: The loop setting the sheet was made with. false is a one-shot animation (an attack, a death) that should play once in an engine.
  - `out_of_frame` boolean: true when Ludo detected the sprite running past the edges of the frame during the animation, so parts of it are cut off. It is a hint, not a guarantee: look at the frames. The cut is in the generated video, so adjustSpritesheet can't recover it. Call editSpritesheet with edit_mode "outpaint" to extend the frame beyond its borders, or generate again with a larger margin on the axis that was cut (margin_ratio_horizontal / margin_ratio_vertical).
  - `bad_loop` boolean: true when Ludo detected that the animation doesn't loop cleanly. It is a hint, not a guarantee. Call editSpritesheet with edit_mode "fix_loop" to repair the loop.
  - `request_id` string
  - `created_at` integer

## Other responses

- `202`: Accepted - the generation was queued; poll GET /assets/jobs/{id}. A synchronous (async: false) call still running after 15 minutes also receives this.
- `400`: Error

## Changes

- **2026-10-05** `6116b014edd6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ludo/apis/ludo-ai-api/changes/assets/sprite/adjust/post.md)

---

[API](https://skmtc.dev/ludo/apis/ludo-ai-api.md) - [All operations](https://skmtc.dev/ludo/apis/ludo-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ludo/apis/ludo-ai-api/revisions/4efeb12a23c9?raw)