---
title: "Preview Directional Sprites: a few frames of a 3D model in a style, from each direction asked for, to check a style before rendering. Takes the same model, animation, camera and style fields as createDirectionalSprites. The response (synchronous, not a job) has one preview per direction, in the order asked, each with `frame_urls` - the frames as images (4 for an animated model, 1 for a still one) - and `render_3d`, the style and settings as rendered, which createDirectionalSprites takes back as they are. Free (no credits), and nothing is saved to your generations; the frame images are kept for 7 days. A preview takes several seconds. You run one preview at a time: starting another while one is still running cancels the older one, which then answers 204 with no body. Preview one or two directions while trying styles and render only once the look is right. Requires an API key (user scope)."
method: POST
path: "/assets/sprite/directional-preview"
tags: ["Spritesheets"]
---

# Preview Directional Sprites: a few frames of a 3D model in a style, from each direction asked for, to check a style before rendering. Takes the same model, animation, camera and style fields as createDirectionalSprites. The response (synchronous, not a job) has one preview per direction, in the order asked, each with \`frame_urls\` - the frames as images (4 for an animated model, 1 for a still one) - and \`render_3d\`, the style and settings as rendered, which createDirectionalSprites takes back as they are. Free (no credits), and nothing is saved to your generations; the frame images are kept for 7 days. A preview takes several seconds. You run one preview at a time: starting another while one is still running cancels the older one, which then answers 204 with no body. Preview one or two directions while trying styles and render only once the look is right. Requires an API key (user scope).

`POST /assets/sprite/directional-preview`

## Request

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

## Request body

- DirectionalPreviewPayload: Payload for previewing directional sprite frames of a 3D model
  - `model` string, required: The 3D model, as a URL or base64-encoded GLB file (not an AI model name). Rigged, to animate it. Up to 30MB; a larger file is rejected with HTTP 400.
  - `animation_url` string: An animation for the model, as a URL or base64-encoded GLB file - the glb_url of an animation from animate3DModel or animate3DModelPreset, made for this model's skeleton. At most one of animation_url, preset_id and model_animation. Up to 30MB; a larger file is rejected with HTTP 400.
  - `preset_id` string: An animation preset id from listAnimationPresets, retargeted onto the model. Any rig type can take one; when the preset cannot be retargeted onto the model, the call returns an error. At most one of animation_url, preset_id and model_animation.
  - `crop_loop` boolean: With preset_id, trim the preset to the span that loops seamlessly. Omit to follow the preset's own loop flag.
  - `model_animation` string: The name of an animation the GLB itself carries. At most one of animation_url, preset_id and model_animation; with none, the preview is a single frame.
  - `perspective` 'horizon' | 'low' | 'isometric' | 'high' | 'top': Camera height, from the side (horizon) to straight down (top).
  - `directions` string[]: Where the camera stands around a character facing S, each direction at most once. One preview per direction, in this order.
  - `style_id` string: A style id from listDirectionalSpriteStyles.
  - `style_version` integer: Version of the style; omit for its current one.
  - `style_params` object: The style's settings to change, by name, each one of its listed option values (true/false for a bool setting, or any colour for a color one). Omit a setting to keep its default.
  - `keep_horizontal_travel` boolean: Keep the animation's ground travel (the character moves across the frame). Off keeps it in place.
  - `keep_vertical_travel` boolean: Keep the animation's vertical root motion (jumps, bobbing).
  - `target_frame_size` integer: Sprite size of the preview frames in pixels (the longer side).

## Response `200`

Success

- DirectionalPreviewResult
  - `previews` DirectionalPreview[]: One preview per direction, in the order asked.
    - `direction` string: The direction this preview is seen from.
    - `frame_urls` string[]: The preview's frames as images, in order (one for a still model). Kept for 7 days.
    - `width` integer
    - `height` integer
    - `num_frames` integer
    - `fps` number, float
    - `render_3d` DirectionalSpriteRender
      - `style_id` string
      - `style_version` integer
      - `style_params` object: The style's settings as rendered, by name.
      - `perspective` string
      - `direction` string
      - `animation_name` string
      - `fps` number, float
      - `keep_horizontal_travel` boolean
      - `keep_vertical_travel` boolean

## Other responses

- `204`: Cancelled by a newer preview of yours
- `400`: Error
- `503`: Previews temporarily unavailable

## Changes

- **2026-10-15** `5386c8cd3d81`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ludo/apis/ludo-ai-api/changes/assets/sprite/directional-preview/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)