openapi: 3.2.0 info: version: 0.9.10 title: Ludo.ai Spritesheets API servers: - url: /api tags: - name: Spritesheets paths: /assets/sprite/animate: post: summary: Animate a static sprite into a spritesheet driven by a motion text prompt… tags: - Spritesheets operationId: animateSprite x-credit-action: ANIMATE_SPRITE security: - ApiKey: [] x-security-scopes: - user responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/SpriteResult' '202': description: 'Accepted - the generation was queued; poll GET /assets/jobs/{id}. A synchronous (async: false) call still running after 15 minutes also receives this.' content: application/json: schema: $ref: '#/components/schemas/PublicJob' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/AnimateSpritePayload' required: true /assets/sprite/animate-keyframes: post: summary: Animate a sprite through up to three fixed keyframes - initial_image… tags: - Spritesheets operationId: animateSpriteKeyframes x-credit-action: ANIMATE_SPRITE x-credit-models: - hydra - hydra-plus - forge - forge-pixel security: - ApiKey: [] x-security-scopes: - user responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/SpriteResult' '202': description: 'Accepted - the generation was queued; poll GET /assets/jobs/{id}. A synchronous (async: false) call still running after 15 minutes also receives this.' content: application/json: schema: $ref: '#/components/schemas/PublicJob' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/AnimateSpriteKeyframesPayload' required: true /assets/sprite/pose: post: summary: Re-pose an existing sprite into a new target pose while preserving the… tags: - Spritesheets operationId: generatePose x-credit-action: GENERATE_IMAGE security: - ApiKey: [] x-security-scopes: - user responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/PoseResult' '202': description: 'Accepted - the generation was queued; poll GET /assets/jobs/{id}. A synchronous (async: false) call still running after 15 minutes also receives this.' content: application/json: schema: $ref: '#/components/schemas/PublicJob' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/GeneratePosePayload' required: true /assets/sprite/rotate: post: summary: Re-render an existing sprite from a different camera viewpoint while keeping… tags: - Spritesheets operationId: rotateSprite x-credit-action: GENERATE_IMAGE security: - ApiKey: [] x-security-scopes: - user responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/RotateSpriteResult' '202': description: 'Accepted - the generation was queued; poll GET /assets/jobs/{id}. A synchronous (async: false) call still running after 15 minutes also receives this.' content: application/json: schema: $ref: '#/components/schemas/PublicJob' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/RotateSpritePayload' required: true /assets/sprite/transfer-motion: post: summary: Transfer motion from a reference video or a named animation preset onto a… tags: - Spritesheets operationId: transferMotion x-credit-action: TRANSFER_SPRITE_MOTION security: - ApiKey: [] x-security-scopes: - user responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/SpriteResult' '202': description: 'Accepted - the generation was queued; poll GET /assets/jobs/{id}. A synchronous (async: false) call still running after 15 minutes also receives this.' content: application/json: schema: $ref: '#/components/schemas/PublicJob' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/TransferMotionPayload' required: true /assets/sprite/animation-presets: get: description: 'List the available animation presets along with their perspectives and the eight supported compass directions (N, NE, E, SE, S, SW, W, NW). Synchronous GET with no request body: it returns an animations array (each with id, name, category, description, duration, and preview_url), a deduplicated perspectives array, and the directions list. This is a free discovery endpoint and does not charge credits. Use it to obtain the preset_id, perspective, and direction values that transferMotion needs, and to find motion preset names you can reference when animating; pair it with transferMotion (to apply a preset onto a sprite), animateSprite (text-prompt animation), or animate3DModelPreset (apply any preset by id to a rigged 3D model). Requires an API key (user scope).' tags: - Spritesheets operationId: listAnimationPresets security: - ApiKey: [] x-security-scopes: - user responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/AnimationPresetsResponse' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: List animation presets x-summary-source: derived /assets/sprite/edit: post: summary: 'Edit a previously generated spritesheet: re-prompt its underlying animation…' tags: - Spritesheets operationId: editSpritesheet x-credit-action: EDIT_SPRITESHEET security: - ApiKey: [] x-security-scopes: - user responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/SpriteResult' '202': description: 'Accepted - the generation was queued; poll GET /assets/jobs/{id}. A synchronous (async: false) call still running after 15 minutes also receives this.' content: application/json: schema: $ref: '#/components/schemas/PublicJob' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/EditSpritesheetPayloadPublic' required: true /assets/sprite/rotate-spritesheet: post: summary: 'Re-render a previously generated sprite animation from a new view: the same…' tags: - Spritesheets operationId: rotateSpritesheet x-cli-name: rotate-sheet x-credit-action: NEW_VIEW_SPRITESHEET security: - ApiKey: [] x-security-scopes: - user responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/SpriteResult' '202': description: 'Accepted - the generation was queued; poll GET /assets/jobs/{id}. A synchronous (async: false) call still running after 15 minutes also receives this.' content: application/json: schema: $ref: '#/components/schemas/PublicJob' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/RotateSpritesheetPayload' required: true /assets/sprite/adjust: post: summary: 'Adjust Sprite Sheet: re-export a previously generated sprite animation with…' tags: - Spritesheets operationId: adjustSpritesheet security: - ApiKey: [] x-security-scopes: - user responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/SpriteResult' '202': description: 'Accepted - the generation was queued; poll GET /assets/jobs/{id}. A synchronous (async: false) call still running after 15 minutes also receives this.' content: application/json: schema: $ref: '#/components/schemas/PublicJob' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/AdjustSpritesheetPayload' required: true /assets/sprite/audio: post: summary: Generate a sound effect for a previously generated spritesheet animation. tags: - Spritesheets operationId: createSpriteAudio x-credit-action: GENERATE_AUDIO_FOR_SPRITES security: - ApiKey: [] x-security-scopes: - user responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/AudioResult' '202': description: 'Accepted - the generation was queued; poll GET /assets/jobs/{id}. A synchronous (async: false) call still running after 15 minutes also receives this.' content: application/json: schema: $ref: '#/components/schemas/PublicJob' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateSpriteAudioPayload' required: true /assets/sprite/directional-styles: get: description: 'List the styles Directional Sprites can render a 3D model in, with the perspectives (camera heights) and the eight directions they render from. Each style has an id (pass it as style_id), a label, a description, a family, whether it is pixel art, a thumbnail_url of the style at its defaults, its current version, and its settings: each setting has a name (the key in style_params), a kind (choice, bool or color - a color setting also takes any colour), its options ({label, value}) and its default. advanced_settings work the same way. Free discovery endpoint: it does not charge credits. Use it before previewDirectionalSprites, createDirectionalSprites and createDirectionalStills. Requires an API key (user scope).' tags: - Spritesheets operationId: listDirectionalSpriteStyles x-cli-name: directional-styles security: - ApiKey: [] x-security-scopes: - user responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/DirectionalSpriteStylesResponse' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: List directional sprite styles x-summary-source: derived /assets/sprite/directional-preview: post: summary: 'Preview Directional Sprites: a few frames of a 3D model in a style, from each…' tags: - Spritesheets operationId: previewDirectionalSprites x-cli-name: directional-preview security: - ApiKey: [] x-security-scopes: - user responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/DirectionalPreviewResult' '204': description: Cancelled by a newer preview of yours '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Previews temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/DirectionalPreviewPayload' required: true /assets/sprite/directional: post: summary: 'Directional Sprites: render a 3D model into one spritesheet per direction, in a…' tags: - Spritesheets operationId: createDirectionalSprites x-cli-name: directional x-credit-action: RENDER_SPRITE_3D security: - ApiKey: [] x-security-scopes: - user responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/DirectionalSpritesResult' '202': description: 'Accepted - the generation was queued; poll GET /assets/jobs/{id}. A synchronous (async: false) call still running after 15 minutes also receives this.' content: application/json: schema: $ref: '#/components/schemas/PublicJob' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/DirectionalSpritesPayload' required: true /assets/sprite/directional-stills: post: summary: 'Directional Sprites stills: render a 3D model as it is (no animation) into one…' tags: - Spritesheets operationId: createDirectionalStills x-cli-name: directional-stills x-credit-action: RENDER_SPRITE_3D_STILL security: - ApiKey: [] x-security-scopes: - user responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/DirectionalStillsResult' '202': description: 'Accepted - the generation was queued; poll GET /assets/jobs/{id}. A synchronous (async: false) call still running after 15 minutes also receives this.' content: application/json: schema: $ref: '#/components/schemas/PublicJob' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/DirectionalStillsPayload' required: true /assets/sprites/results: get: description: '**Deprecated:** prefer `GET /assets/generations` (all types, paginated, same source filter). This endpoint continues to work; no removal is scheduled. List spritesheets you previously generated through the API, most recent first. This is a free read-only history lookup (no credits, no generation); it does not create anything. Pass an optional request_id query parameter to return only the results tagged with that id when you originally called animateSprite or transferMotion. Requires an API key (user scope).' tags: - Spritesheets operationId: getSpriteResults deprecated: true x-mcp-exclude: true security: - ApiKey: [] x-security-scopes: - user parameters: - name: request_id in: query description: Filter results by request_id required: false schema: type: string - name: source in: query description: 'Which surface the results were generated from: api (default, your API/MCP generations from the last 7 days), web (your Ludo web studio generations, no time limit), or all' required: false schema: type: string enum: - api - web - all default: api responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/SpriteResult' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get sprite results x-summary-source: derived components: schemas: DirectionalSpriteRender: type: object properties: style_id: type: string style_version: type: integer style_params: type: object description: The style's settings as rendered, by name. perspective: type: string direction: type: string animation_name: type: string fps: type: number format: float keep_horizontal_travel: type: boolean keep_vertical_travel: type: boolean SpriteResult: type: object properties: spritesheet_url: type: string video_url: type: string audio_url: type: string description: 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: type: string individual_frame_urls: type: array items: type: string num_frames: type: integer description: Number of frames in the spritesheet. num_cols: type: integer description: Columns in the frame grid. Frames run left-to-right, top-to-bottom. num_rows: type: integer description: Rows in the frame grid. The last row may be only partly filled. spritesheet_with_background_url: type: string individual_frame_with_background_urls: type: array items: type: string duration: type: number format: float request_id: type: string created_at: type: integer DirectionalPreviewPayload: type: object required: - model properties: model: type: string description: The 3D model, as a URL or base64-encoded GLB file (not an AI model name). Rigged, to animate it. animation_url: type: string description: 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. preset_id: type: string description: 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: type: boolean description: With preset_id, trim the preset to the span that loops seamlessly. Omit to follow the preset's own loop flag. model_animation: type: string description: 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: type: string default: isometric description: Camera height, from the side (horizon) to straight down (top). enum: - horizon - low - isometric - high - top directions: type: array default: - SW minItems: 1 maxItems: 8 uniqueItems: true description: Where the camera stands around a character facing S, each direction at most once. One preview per direction, in this order. items: type: string enum: - S - SW - W - NW - N - NE - E - SE style_id: type: string default: render_3d description: A style id from listDirectionalSpriteStyles. style_version: type: integer description: Version of the style; omit for its current one. style_params: type: object description: 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: type: boolean default: false description: Keep the animation's ground travel (the character moves across the frame). Off keeps it in place. keep_vertical_travel: type: boolean default: true description: Keep the animation's vertical root motion (jumps, bobbing). target_frame_size: type: integer minimum: 32 maximum: 384 default: 256 description: Sprite size of the preview frames in pixels (the longer side). RotateSpritePayload: type: object description: Payload for rotating the camera view of an existing sprite required: - image - camera_rotation properties: image: type: string description: URL or base64-encoded source sprite image to rotate. camera_rotation: type: integer enum: - 0 - 45 - 90 - 135 - 180 - -135 - -90 - -45 description: Camera azimuth angle in degrees. 0 = front, 45 = front-right, 90 = right side, 135 = back-right, 180 = back, -135 = back-left, -90 = left side, -45 = front-left. camera_elevation: type: integer enum: - 0 - 30 - 60 description: Optional camera elevation/tilt in degrees. 0 = eye-level, 30 = elevated, 60 = high-angle. Omit to keep the sprite's current elevation. n: type: number format: integer description: Number of variations to generate (1-4). minimum: 1 maximum: 4 default: 1 augment_prompt: type: boolean default: true description: Rewrites your prompt behind the scenes into the form the model works best with. Leave it on (the default). Turning it off does not give you more control - it usually gives worse results. Do not disable it unless you really know what you are doing and have tested your prompts extensively. request_id: type: string description: 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: type: boolean default: true description: '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.' DirectionalStill: type: object properties: direction: type: string description: The direction this image is seen from. url: type: string width: type: integer height: type: integer render_3d: $ref: '#/components/schemas/DirectionalSpriteRender' DirectionalSpriteSheet: type: object properties: direction: type: string description: The direction this sheet is seen from. spritesheet_url: type: string video_url: type: string gif_url: type: string individual_frame_urls: type: array items: type: string num_frames: type: integer description: Number of frames in the spritesheet. num_cols: type: integer description: Columns in the frame grid. Frames run left-to-right, top-to-bottom. num_rows: type: integer description: Rows in the frame grid. The last row may be only partly filled. fps: type: number format: float description: The frame rate the sheet plays at. render_3d: $ref: '#/components/schemas/DirectionalSpriteRender' AnimationPresetsResponse: type: object properties: animations: type: array items: $ref: '#/components/schemas/AnimationPresetPublic' perspectives: type: array items: $ref: '#/components/schemas/AnimationPerspective' directions: type: array items: type: string RotateSpriteResult: type: object description: Result of a sprite camera rotation properties: url: type: string description: URL of the generated image camera_rotation: type: integer description: The camera azimuth angle that was applied camera_elevation: type: integer description: The camera elevation that was applied, if any DirectionalSpriteStylesResponse: type: object properties: styles: type: array items: $ref: '#/components/schemas/DirectionalSpriteStyle' perspectives: type: array items: type: string directions: type: array items: type: string EditSpritesheetPayloadPublic: type: object description: Payload for editing a previously generated spritesheet. edit_mode selects the operation - prompt-driven edit (default), outpaint, loop fixing, or improve (finer detail, on hydra spritesheets only). required: - spritesheet_url properties: spritesheet_url: type: string description: 'URL of a spritesheet you generated in the last 7 days (returned by animateSprite, transferMotion, or a previous edit as spritesheet_url). External URLs are not accepted. Edit the original animation rather than a previous edit''s result: every edit re-renders the whole animation, so colors and detail drift further with each pass. If an edit did not work, retry from the original instead of editing on top.' edit_mode: type: string description: Edit operation to perform. "improve" re-renders the animation with finer detail (the extra pass hydra-plus runs when it generates) and only takes a spritesheet generated with hydra; any other source returns HTTP 400, including an already improved spritesheet (or a loop fix or outpaint of one), which has that detail already. enum: - prompt - outpaint - fix_loop - improve default: prompt prompt: type: string description: Edit instruction. Required for edit_mode "prompt", optional for "outpaint", not accepted for "fix_loop" or "improve". Focus it on a single change and keep it short (under about 50 words); run a second edit for more. images: type: array maxItems: 5 items: type: string description: 'Optional reference images (up to 5), each a URL or base64, to guide the edit. Two, at most three, work best: more references reduce the model''s ability to use any of them correctly.' duration: x-no-example: true type: number format: float description: Output animation length in seconds. Omit to keep the source spritesheet's duration (recommended). Prices a prompt edit; outpaint, fix_loop and improve are billed on the source spritesheet's video length whatever this is. model: x-no-example: true type: string description: Backing model for edit_mode "prompt" (ignored for "outpaint", "fix_loop" and "improve", which run a fixed pipeline). Hydra is the default and the most capable, and generates audio; forge is the cheaper pick for simple edits; forge-pixel is the pixel-art variant, for spritesheets whose frames are pixel art. enum: - hydra - forge - forge-pixel default: hydra crop: x-no-example: true type: boolean description: Crop sprite frames to fit content (omit to keep the source spritesheet's setting). Results in smaller spritesheets but inconsistent frame sizes across different animations. loop: x-no-example: true type: boolean default: true description: Trim the animation at the beginning or end to create a seamless loop. frames: x-no-example: true type: number format: integer description: Number of frames in the output spritesheet. Omit to keep the source spritesheet's frame count. Allow about one second of duration per 16 frames - above that the model may not be able to produce them all. enum: - 4 - 9 - 16 - 25 - 36 - 49 - 64 frame_size: x-no-example: true type: number format: integer description: 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. 0 is for maximum resolution. Omit to keep the source spritesheet's setting. enum: - 32 - 64 - 96 - 128 - 192 - 256 - 384 - 0 gif: type: boolean default: false description: When true, generates an animated GIF from the spritesheet and returns it in gif_url. Disabled by default to reduce response time. individual_frames: type: boolean default: false description: When true, extracts each frame from the spritesheet as an individual image and returns the URLs in individual_frame_urls. spritesheet_with_background: type: boolean default: false description: When true, also returns the spritesheet with background intact (before background removal). The with-background spritesheet URL will be in spritesheet_with_background_url. request_id: type: string description: 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: type: boolean default: true description: '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.' AnimationPerspective: type: object properties: id: type: string name: type: string description: type: string PublicJobError: type: object properties: status: type: integer format: int32 message: type: string CreateSpriteAudioPayload: type: object description: Payload for generating audio for a previously generated spritesheet animation. required: - spritesheet_video_url properties: spritesheet_video_url: type: string description: The video_url of a spritesheet you generated in the last 7 days (returned by animateSprite, animateSpriteKeyframes, transferMotion, or editSpritesheet). External URLs are not accepted. prompt: type: string description: Optional description of the sound to generate. request_id: type: string description: Optional client-provided identifier, unique per request. Re-sending the same request_id returns the existing job instead of generating again. It does not re-tag the spritesheet, which keeps the request_id it was generated with. async: type: boolean default: true description: '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.' DirectionalStillsResult: type: object properties: images: type: array description: One image per direction, in the order asked. items: $ref: '#/components/schemas/DirectionalStill' AnimateSpritePayload: type: object description: Payload for generating an animated spritesheet from a static image. Input images can either be provided in base64 or URL. If the image was generated using Ludo, ideally it should be generated using the "sprite", "sprite-vfx" or "ui_asset" type. required: - motion_prompt - initial_image properties: motion_prompt: type: string description: 'Text description of the desired animation, e.g. "walking", "idle breathing", "attack slash", "casting a fireball with both hands". Describe exactly and unambiguously what the character should do. Specific or complex actions are fine; there is no need to simplify them. Do not over-describe, though: too much detail can harm the animation, and an action the model already knows should be named, not decomposed into its steps ("walking", never "move the left foot forward, then the right foot"). Do not restate what initial_image already shows (the character, its appearance and equipment, the art style, the background, the lighting, the camera), and leave frame count and timing to the frames and duration fields. Negative phrasing ("no background", "do not move the camera", "without a weapon") works only on hydra and hydra-plus. On forge, forge-pixel and the legacy models it backfires: naming something you do not want makes it more likely to appear, so "without a weapon" tends to produce a weapon. On those models never phrase anything negatively; state only what should happen, and control everything else through the image and the other fields. Keep it well under 100 words: in longer prompts details start competing and some get dropped.' initial_image: type: string description: The url OR base64 of the starting frame image to animate. This is the base sprite that will be brought to life. final_image: type: string description: The url OR base64 of ending frame image. When provided, the animation will interpolate between the initial and final frames. loop: type: boolean default: true description: Trim the animation at the beginning or end to create a seamless loop. Not guaranteed to produce a perfect loop. crop: type: boolean default: true description: Crop sprite frames to fit content. Results in smaller spritesheets but inconsistent frame sizes across different animations. frames: type: number format: integer description: Maximum number of frames in the output spritesheet. Allow about one second of duration per 16 frames - above that the model may not be able to produce them all (64 frames needs a duration of at least 4). The result can have fewer frames when the duration is short or bad frames were removed. default: 36 enum: - 4 - 9 - 16 - 25 - 36 - 49 - 64 frame_size: type: number format: integer description: 'Size of the sprite in pixels, not of the frame: it sets how big the character is drawn in the exported sheet, and each frame also holds the space around the sprite, so frames come out larger than this value. It changes the export only, not how the sprite is generated. 0 is maximum resolution. -1 is AI 1.5x upscaling. -9 is True Size: frames keep the size and position of the input frame, untrimmed, so the spritesheet lines up exactly with the input image - use it (not margin_ratio_mode "none") whenever the output must align with your input; it works with any margin mode. Exporting larger than the input image adds no detail: do not pick a size above the input''s own resolution, and 0 or -1 gain nothing on inputs under 512 px. True Size crops at the input image''s edges, so anything the animation adds beyond them (an aura, a spell effect, a swung weapon) is cut off: use a fixed size or 0 for those. adjustSpritesheet re-exports a finished animation at another size for free.' default: 0 enum: - 32 - 64 - 96 - 128 - 192 - 256 - 384 - 0 - -1 - -9 margin_ratio: type: number format: float x-deprecated: true description: 'Deprecated: prefer margin_ratio_horizontal / margin_ratio_vertical. Amount of padding around the sprite as a ratio (0.0 to 1.0). Sets both axes to this value. A per-axis value, when also given, overrides this for that axis. Supplying any margin value selects margin_ratio_mode "manual" unless margin_ratio_mode is set explicitly.' margin_ratio_horizontal: type: number format: float description: Horizontal padding around the sprite as a ratio (0.0 to 1.0). Every bit of margin is resolution taken from the sprite, so keep it as tight as the motion allows - about 0.15 - and go higher only for motion that extends sideways (sword slashes, punches) or if the sprite gets cut off. Supplying a value selects margin_ratio_mode "manual" unless margin_ratio_mode is set explicitly; overrides the legacy margin_ratio on this axis. margin_ratio_vertical: type: number format: float description: Vertical padding around the sprite as a ratio (0.0 to 1.0). Every bit of margin is resolution taken from the sprite, so keep it as tight as the motion allows - about 0.15 - and go higher only for motion that extends up or down (jumps) or if the sprite gets cut off. Supplying a value selects margin_ratio_mode "manual" unless margin_ratio_mode is set explicitly; overrides the legacy margin_ratio on this axis. margin_ratio_mode: type: string description: 'How the sprite is framed for generation. The model always generates on a canvas of the same size, so any margin is canvas the sprite does not fill: the more margin, the lower the resolution and detail of the sprite. "auto" (default, recommended) trims and centers the sprite and picks a margin suited to the motion. "manual" uses margin_ratio_horizontal / margin_ratio_vertical; keep them as tight as the motion allows (about 0.15) and raise only the axis the motion needs. "none" animates the input exactly as framed, with no trimming and no margin added, so the input must already have suitable margins: a sprite touching the edges gets its limbs, weapons and effects cut off as soon as it moves, and an image that is mostly empty space yields a small, low-detail sprite. "none" is the way to keep a deliberately off-center sprite (e.g. a character at the left edge firing a beam to the right), but results can be unpredictable. Do not use "none" to make the spritesheet line up with the input image - use frame_size -9 (True Size) for that; it works with any margin mode. Rules: omit margin_ratio_mode and send margin_ratio_horizontal / margin_ratio_vertical to get "manual" automatically; "manual" with no margin value fails with HTTP 400; "auto" or "none" sent together with a margin value fails with HTTP 400 (the value would be ignored).' enum: - auto - manual - none default: auto image_type: x-swagger-data: spriteImageTypes type: string description: Type of sprite being animated. Affects generation parameters and styling. Tiling types (horizontal / vertical tiles, scrolling backgrounds, parallax layers, textures) stay seamless only on forge and forge-pixel, and only if the input image itself already wraps seamlessly on that axis; otherwise the animation shows a visible seam when tiled. default: sprite model: type: string x-model-notes: forge-pixel expects real pixel art - a perfect pixel grid at its natural resolution; for other art use hydra or forge. Tiling image types stay seamless only on forge and forge-pixel. description: Animation model to use. hydra is the most capable and generates audio; forge is best for basic animations and relatively simple sprites; forge-pixel for pixel art. blitz (default), eagle and eagle-audio are legacy models kept for existing integrations. enum: - hydra - hydra-plus - forge - forge-pixel - blitz - eagle - eagle-audio - standard default: hydra duration: type: number format: float default: 3 description: Animation length in seconds. Available values depend on the model - the source of truth is MODEL_PRICING (credits.js), surfaced via /credits/costs; the public API docs list them per model (auto-generated). augment_prompt: type: boolean default: true description: Rewrites your prompt behind the scenes into the form the model works best with. Leave it on (the default). Turning it off does not give you more control - it usually gives worse results. Do not disable it unless you really know what you are doing and have tested your prompts extensively. gif: type: boolean default: false description: When true, generates an animated GIF from the spritesheet and returns it in gif_url. Disabled by default to reduce response time. individual_frames: type: boolean default: false description: When true, extracts each frame from the spritesheet as an individual image and returns the URLs in individual_frame_urls. spritesheet_with_background: type: boolean default: false description: When true, also returns the spritesheet with background intact (before background removal). Useful for manually fixing background removal issues. The with-background spritesheet URL will be in spritesheet_with_background_url. request_id: type: string description: 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: type: boolean default: true description: '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.' AudioResult: type: object properties: url: type: string description: 'URL of the generated audio file: MP3 or WAV; the extension (.mp3 or .wav) says which.' type: type: string duration: type: number format: float request_id: type: string created_at: type: integer ErrorResponse: type: object properties: message: type: string metadata: type: string error_payload: type: string intent: type: object description: Stripe intent details sent with 3D Secure (406) errors properties: id: type: string type: type: string enum: - payment - setup client_secret: type: string DirectionalStillsPayload: type: object required: - model properties: model: type: string description: The 3D model, as a URL or base64-encoded GLB file (not an AI model name). Rendered as it is, in its rest pose. perspective: type: string default: isometric description: Camera height, from the side (horizon) to straight down (top). enum: - horizon - low - isometric - high - top directions: type: array default: - SW minItems: 1 maxItems: 8 uniqueItems: true description: Where the camera stands around a character facing S, each direction at most once. One image per direction, in this order, rendered together so they line up. items: type: string enum: - S - SW - W - NW - N - NE - E - SE style_id: type: string default: render_3d description: A style id from listDirectionalSpriteStyles. style_version: type: integer description: Version of the style; omit for its current one. style_params: type: object description: 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. request_id: type: string description: 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: type: boolean default: true description: '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.' TransferMotionPayload: type: object description: Payload for transferring motion from a video onto a static sprite image, producing an animated spritesheet. required: - image properties: image: type: string description: The static sprite to animate, as a URL or base64 image. Ideally an image generated with the "sprite", "sprite-vfx" or "ui_asset" image type. video: type: string description: URL of the video to use as motion source - the `video_url` of a spritesheet from animateSprite, or your own clip. Videos up to 4 seconds work best. Either `video` or `preset_id` + `perspective` + `direction` must be provided; when both are sent the video is used. A video more than twice as long as `duration` gets heavily compressed and the motion turns rushed - trim it to the part you want, or raise `duration`. preset_id: type: string description: ID of an animation preset to use instead of a video URL. Use listAnimationPresets to list available presets. When using a preset, `perspective` and `direction` are required. direction: type: string description: Direction for the animation preset. When using a preset, `direction` is required. enum: - N - NE - E - SE - S - SW - W - NW perspective: x-swagger-data: animationPerspectives type: string description: 'Camera perspective of the preset clip, by id (the `perspectives` list of listAnimationPresets, the same set for every preset): high = tactical steep top-down, horizon = side view at eye level, isometric = diagonal top-down with depth, low = hero low angle, top = directly overhead. Required when using a preset. Unrelated to the `perspective` of createImage, which is a free-text art direction.' frames: type: number format: integer description: Maximum number of frames in the output spritesheet. Allow about one second of duration per 16 frames - above that the model may not be able to produce them all (64 frames needs a duration of at least 4). The result can have fewer frames when the duration is short or bad frames were removed. default: 36 enum: - 4 - 9 - 16 - 25 - 36 - 49 - 64 frame_size: type: number format: integer description: 'Size of the sprite in pixels, not of the frame: it sets how big the character is drawn in the exported sheet, and each frame also holds the space around the sprite, so frames come out larger than this value. 0 is maximum resolution. Exporting larger than the input image adds no detail: do not pick a size above the input''s own resolution, and 0 gains nothing on inputs under 512 px. True Size is not available here: the image is not the first frame of the result, so there is nothing to align to.' default: 0 enum: - 32 - 64 - 96 - 128 - 192 - 256 - 384 - 0 loop: type: boolean default: true description: Trim the animation at the beginning or end to create a seamless loop. crop: type: boolean default: true description: Crop sprite frames to fit content. Results in smaller spritesheets but inconsistent frame sizes across different animations. margin_ratio: type: number format: float x-deprecated: true description: 'Deprecated: prefer margin_ratio_horizontal / margin_ratio_vertical. Amount of padding around the sprite as a ratio (0.0 to 1.0). Sets both axes to this value. A per-axis value, when also given, overrides this for that axis. Defaults to 0.15 when no margin value is given at all.' margin_ratio_horizontal: type: number format: float description: Horizontal padding around the sprite as a ratio (0.0 to 1.0). Every bit of margin is resolution taken from the sprite, so keep it as tight as the motion allows - about 0.15 - and go higher only for motion that extends sideways (sword slashes, punches) or if the sprite gets cut off. Overrides the legacy margin_ratio on this axis. margin_ratio_vertical: type: number format: float description: Vertical padding around the sprite as a ratio (0.0 to 1.0). Every bit of margin is resolution taken from the sprite, so keep it as tight as the motion allows - about 0.15 - and go higher only for motion that extends up or down (jumps) or if the sprite gets cut off. Overrides the legacy margin_ratio on this axis. margin_ratio_mode: type: string description: 'How the sprite is framed for generation. Defaults to "manual" (0.15 on each axis when no margin value is given); transfer motion has no "auto". The model always generates on a canvas of the same size, so any margin is canvas the sprite does not fill: the more margin, the lower the resolution and detail of the sprite. Keep the margins tight - about 0.15 - and raise only the axis the motion needs. "none" animates the image exactly as framed, so it must already have suitable margins (not touching the edges, not mostly empty space); an off-center sprite can give unpredictable results. Sending "none" together with a margin value fails with HTTP 400 (the value would be ignored).' enum: - manual - none default: manual gif: type: boolean default: false description: When true, generates an animated GIF from the spritesheet and returns it in gif_url. Disabled by default to reduce response time. individual_frames: type: boolean default: false description: When true, extracts each frame from the spritesheet as an individual image and returns the URLs in individual_frame_urls. spritesheet_with_background: type: boolean default: false description: When true, also returns the spritesheet with background intact (before background removal). Useful for manually fixing background removal issues. The with-background spritesheet URL will be in spritesheet_with_background_url. model: type: string x-model-notes: forge is tuned for the motion presets (preset_id) and often fails to follow your own video - use hydra for custom footage. forge-pixel expects real pixel art - a perfect pixel grid at its natural resolution. description: Motion transfer model to use. Hydra is the most capable and generates audio; Forge is cost-effective for simple motion; Tango is a legacy model kept for existing integrations. enum: - hydra - forge - forge-pixel - tango default: hydra prompt: type: string description: Optional extra instructions for the motion transfer (e.g. "keep the cape still"), added to the model's own prompt. duration: type: number format: float default: 1.5 description: Animation length in seconds. If the reference video is longer, it will be compressed to this duration. Available values depend on the model - see /credits/costs (per-model lists are auto-generated into the public API docs). request_id: type: string description: 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: type: boolean default: true description: '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.' RotateSpritesheetPayload: type: object description: Payload for re-rendering a previously generated sprite animation from a new view. required: - spritesheet_url - image properties: spritesheet_url: type: string description: URL of a spritesheet you generated in the last 7 days (returned by animateSprite, animateSpriteKeyframes, transferMotion or editSpritesheet as spritesheet_url). External URLs are not accepted. image: type: string description: The character exactly as it must appear in the new view, as a URL or base64. It becomes the first frame of the animation. rotateSprite produces one from the animation's first frame. final_image: x-no-example: true type: string description: Optional exact last frame (URL or base64). Defaults to the first frame, for cyclic or returning animations. prompt: type: string description: Optional instructions - the character's facing in the new view ("its back to the camera"), where the action goes ("the kick goes to the left of the frame"), or anything else about the motion. duration: x-no-example: true type: number format: float minimum: 1 maximum: 5 description: Seconds of the source animation to re-render; a longer source is sped up to fit. Omit to use the source's own length, capped at 5 (recommended). model: x-no-example: true type: string description: Backing model. Only hydra and hydra-plus support new views. enum: - hydra - hydra-plus default: hydra loop: x-no-example: true type: boolean description: Trim the animation at the beginning or end to create a seamless loop. Omit to keep the source spritesheet's setting. crop: x-no-example: true type: boolean default: true description: Crop sprite frames to fit content. Results in smaller spritesheets but inconsistent frame sizes across different animations. frames: x-no-example: true type: number format: integer description: Number of frames in the output spritesheet. Omit to keep the source spritesheet's frame count. Allow about one second of duration per 16 frames - above that the model may not be able to produce them all. enum: - 4 - 9 - 16 - 25 - 36 - 49 - 64 frame_size: x-no-example: true type: number format: integer description: 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. 0 is for maximum resolution. Omit to keep the source spritesheet's setting. enum: - 32 - 64 - 96 - 128 - 192 - 256 - 384 - 0 gif: type: boolean default: false description: When true, generates an animated GIF from the spritesheet and returns it in gif_url. Disabled by default to reduce response time. individual_frames: type: boolean default: false description: When true, extracts each frame from the spritesheet as an individual image and returns the URLs in individual_frame_urls. spritesheet_with_background: type: boolean default: false description: When true, also returns the spritesheet with background intact (before background removal). The with-background spritesheet URL will be in spritesheet_with_background_url. request_id: type: string description: 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: type: boolean default: true description: '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.' AnimationPresetPublic: type: object properties: id: type: string name: type: string category: type: string description: type: string duration: type: number format: float preview_url: type: string AnimateSpriteKeyframesPayload: type: object description: Payload for generating an animated spritesheet that interpolates through up to three fixed keyframes (initial / middle / final). Runs on hydra (default), hydra-plus, forge or forge-pixel - the models supporting a middle keyframe. Input images can be provided in base64 or URL. At least one of initial_image or middle_image must be provided. properties: motion_prompt: type: string description: 'Optional text description of the desired animation, e.g. "walking", "attack slash". When omitted, the motion is derived purely from the keyframes. When provided, describe exactly and unambiguously what the character should do. Specific or complex actions are fine; there is no need to simplify them. Do not over-describe, though: too much detail can harm the animation, and an action the model already knows should be named, not decomposed into its steps ("walking", never "move the left foot forward, then the right foot"). Do not restate what the keyframes already show (the character, its appearance and equipment, the art style, the background, the lighting, the camera), and leave frame count and timing to the frames and duration fields. Negative phrasing ("no background", "do not move the camera", "without a weapon") works only on hydra and hydra-plus. On forge and forge-pixel it backfires: naming something you do not want makes it more likely to appear, so "without a weapon" tends to produce a weapon. On those models never phrase anything negatively; state only what should happen, and control everything else through the keyframes and the other fields. Keep it well under 100 words: in longer prompts details start competing and some get dropped.' initial_image: type: string description: The url OR base64 of the first keyframe. Optional when a middle_image is provided. middle_image: type: string description: The url OR base64 of the middle keyframe the animation passes through between the initial and final frames. Consecutive keyframes must differ - two identical keyframes in a row produce no motion across that span. final_image: type: string description: The url OR base64 of the final keyframe. Requires an initial_image or middle_image to anchor the animation. model: type: string x-model-notes: forge-pixel expects real pixel art - a perfect pixel grid at its natural resolution; for other art use hydra or forge. Tiling image types stay seamless only on forge and forge-pixel. description: Backing model. Hydra (most capable, generates audio) and the Forge family support a middle keyframe; forge-pixel is the pixel-art variant, for sprites whose frames are pixel art. enum: - hydra - hydra-plus - forge - forge-pixel default: hydra loop: type: boolean default: true description: Trim the animation at the beginning or end to create a seamless loop. Not guaranteed to produce a perfect loop. crop: type: boolean default: true description: Crop sprite frames to fit content. Results in smaller spritesheets but inconsistent frame sizes across different animations. frames: type: number format: integer description: Maximum number of frames in the output spritesheet. Allow about one second of duration per 16 frames - above that the model may not be able to produce them all (64 frames needs a duration of at least 4). The result can have fewer frames when the duration is short or bad frames were removed. default: 36 enum: - 4 - 9 - 16 - 25 - 36 - 49 - 64 frame_size: type: number format: integer description: 'Size of the sprite in pixels, not of the frame: it sets how big the character is drawn in the exported sheet, and each frame also holds the space around the sprite, so frames come out larger than this value. It changes the export only, not how the sprite is generated. 0 is maximum resolution. -1 is AI 1.5x upscaling. -9 is True Size: frames keep the size and position of the input frame, untrimmed, so the spritesheet lines up exactly with the input image - use it (not margin_ratio_mode "none") whenever the output must align with your input; it works with any margin mode. Exporting larger than the input image adds no detail: do not pick a size above the input''s own resolution, and 0 or -1 gain nothing on inputs under 512 px. True Size crops at the input image''s edges, so anything the animation adds beyond them (an aura, a spell effect, a swung weapon) is cut off: use a fixed size or 0 for those. adjustSpritesheet re-exports a finished animation at another size for free.' default: 0 enum: - 32 - 64 - 96 - 128 - 192 - 256 - 384 - 0 - -1 - -9 margin_ratio: type: number format: float x-deprecated: true description: 'Deprecated: prefer margin_ratio_horizontal / margin_ratio_vertical. Amount of padding around the sprite as a ratio (0.0 to 1.0). Sets both axes to this value. A per-axis value, when also given, overrides this for that axis. Supplying any margin value selects margin_ratio_mode "manual" unless margin_ratio_mode is set explicitly.' margin_ratio_horizontal: type: number format: float description: Horizontal padding around the sprite as a ratio (0.0 to 1.0). Every bit of margin is resolution taken from the sprite, so keep it as tight as the motion allows - about 0.15 - and go higher only for motion that extends sideways (sword slashes, punches) or if the sprite gets cut off. Supplying a value selects margin_ratio_mode "manual" unless margin_ratio_mode is set explicitly; overrides the legacy margin_ratio on this axis. margin_ratio_vertical: type: number format: float description: Vertical padding around the sprite as a ratio (0.0 to 1.0). Every bit of margin is resolution taken from the sprite, so keep it as tight as the motion allows - about 0.15 - and go higher only for motion that extends up or down (jumps) or if the sprite gets cut off. Supplying a value selects margin_ratio_mode "manual" unless margin_ratio_mode is set explicitly; overrides the legacy margin_ratio on this axis. margin_ratio_mode: type: string description: 'How the sprite is framed for generation. The model always generates on a canvas of the same size, so any margin is canvas the sprite does not fill: the more margin, the lower the resolution and detail of the sprite. "auto" (default, recommended) trims and centers the sprite and picks a margin suited to the motion. "manual" uses margin_ratio_horizontal / margin_ratio_vertical; keep them as tight as the motion allows (about 0.15) and raise only the axis the motion needs. "none" animates the input exactly as framed, with no trimming and no margin added, so the input must already have suitable margins: a sprite touching the edges gets its limbs, weapons and effects cut off as soon as it moves, and an image that is mostly empty space yields a small, low-detail sprite. "none" is the way to keep a deliberately off-center sprite (e.g. a character at the left edge firing a beam to the right), but results can be unpredictable. Do not use "none" to make the spritesheet line up with the input image - use frame_size -9 (True Size) for that; it works with any margin mode. Rules: omit margin_ratio_mode and send margin_ratio_horizontal / margin_ratio_vertical to get "manual" automatically; "manual" with no margin value fails with HTTP 400; "auto" or "none" sent together with a margin value fails with HTTP 400 (the value would be ignored).' enum: - auto - manual - none default: auto image_type: x-swagger-data: spriteImageTypes type: string description: Type of sprite being animated. Affects generation parameters and styling. Tiling types (horizontal / vertical tiles, scrolling backgrounds, parallax layers, textures) stay seamless only on forge and forge-pixel, and only if the input image itself already wraps seamlessly on that axis; otherwise the animation shows a visible seam when tiled. default: sprite duration: type: number format: float default: 3 description: Animation length in seconds. This endpoint always runs on the Forge model, so only Forge's durations apply - the source of truth is MODEL_PRICING (credits.js), surfaced via /credits/costs. augment_prompt: type: boolean default: true description: Rewrites your prompt behind the scenes into the form the model works best with. Leave it on (the default). Turning it off does not give you more control - it usually gives worse results. Do not disable it unless you really know what you are doing and have tested your prompts extensively. gif: type: boolean default: false description: When true, generates an animated GIF from the spritesheet and returns it in gif_url. Disabled by default to reduce response time. individual_frames: type: boolean default: false description: When true, extracts each frame from the spritesheet as an individual image and returns the URLs in individual_frame_urls. spritesheet_with_background: type: boolean default: false description: When true, also returns the spritesheet with background intact (before background removal). Useful for manually fixing background removal issues. The with-background spritesheet URL will be in spritesheet_with_background_url. request_id: type: string description: 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: type: boolean default: true description: '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.' DirectionalSpriteStyle: type: object properties: id: type: string description: Pass as style_id. label: type: string description: type: string family: type: string pixel: type: boolean description: Whether the style is pixel art. thumbnail_url: type: string description: The style at its defaults. version: type: integer description: The style's current version. settings: type: array description: 'The style''s settings: each has a name (its key in style_params), label, description, kind (choice, bool or color), options ({label, value}) and default.' items: type: object advanced_settings: type: array description: Finer settings, described the same way. items: type: object AdjustSpritesheetPayload: type: object description: Payload for re-exporting a previously generated sprite animation with different sheet settings (Adjust Sprite Sheet in the web app). required: - spritesheet_url properties: spritesheet_url: type: string description: 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: x-no-example: true type: number format: integer description: Number of frames in the new sheet. Omit to keep the source's frame count. enum: - 4 - 9 - 16 - 25 - 36 - 49 - 64 frame_size: x-no-example: true type: number format: integer description: '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.' enum: - 32 - 64 - 96 - 128 - 192 - 256 - 384 - 0 - -1 - -9 loop: x-no-example: true type: boolean description: Trim the animation at the beginning or end to create a seamless loop. Omit to keep the source's setting. crop: x-no-example: true type: boolean description: 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: type: boolean default: false description: When true, generates an animated GIF from the spritesheet and returns it in gif_url. Disabled by default to reduce response time. individual_frames: type: boolean default: false description: When true, extracts each frame from the spritesheet as an individual image and returns the URLs in individual_frame_urls. spritesheet_with_background: type: boolean default: false description: When true, also returns the spritesheet with background intact (before background removal). The with-background spritesheet URL will be in spritesheet_with_background_url. request_id: type: string description: 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: type: boolean default: true description: '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.' PoseResult: type: object description: Result of a pose generation properties: url: type: string description: URL of the generated pose image pose: type: string description: The pose that was used to generate this image description: type: string description: The pose description that was used to generate this image motion_prompt: type: string description: A suggested motion prompt optimized for this pose. Can be used directly with 'animateSprite' for best animation results. DirectionalSpritesPayload: type: object required: - model properties: model: type: string description: The 3D model, as a URL or base64-encoded GLB file (not an AI model name). Rigged, to animate it. animation_url: type: string description: 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. preset_id: type: string description: 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: type: boolean description: With preset_id, trim the preset to the span that loops seamlessly. Omit to follow the preset's own loop flag. model_animation: type: string description: The name of an animation the GLB itself carries. At most one of animation_url, preset_id and model_animation; with none, each sheet is a single frame. perspective: type: string default: isometric description: Camera height, from the side (horizon) to straight down (top). enum: - horizon - low - isometric - high - top directions: type: array default: - SW minItems: 1 maxItems: 8 uniqueItems: true description: Where the camera stands around a character facing S, each direction at most once. One sheet per direction, in this order, rendered together on the same frame size, scale and floor so they line up. items: type: string enum: - S - SW - W - NW - N - NE - E - SE style_id: type: string default: render_3d description: A style id from listDirectionalSpriteStyles. style_version: type: integer description: Version of the style; omit for its current one. A render_3d from an earlier result names the version it was rendered with. style_params: type: object description: 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: type: boolean default: false description: Keep the animation's ground travel (the character moves across the frame). Off keeps it in place. keep_vertical_travel: type: boolean default: true description: Keep the animation's vertical root motion (jumps, bobbing). target_frame_size: type: integer minimum: 32 maximum: 640 default: 640 description: Sprite size in pixels - the longer side of the frame, which every direction shares. num_frames: type: integer minimum: 4 maximum: 100 default: 36 description: Frames per sheet, sampled over the animation; moved to the nearest count that fills the sheet grid, and never more than the animation's keyframes. A still model gives one. loop: type: boolean description: Sample the animation as a seamless loop. Omit to follow the animation's own loop flag. gif: type: boolean default: false description: Also return each sheet as an animated GIF (gif_url). individual_frames: type: boolean default: false description: Also return each sheet's frames as separate images (individual_frame_urls). request_id: type: string description: 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: type: boolean default: true description: '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.' GeneratePosePayload: type: object description: Payload for generating a new pose for an existing sprite required: - image - pose properties: image: type: string description: URL or base64-encoded source sprite image to generate a new pose from. pose: type: string x-swagger-data: spritePoses description: Target pose for the sprite. Use the value "Other" to generate other poses not listed in the accepted values, and fill the field description accordingly. description: type: string description: Optional additional instructions or description to guide the pose generation. n: type: number format: integer description: Number of pose variations to generate (1-4). minimum: 1 maximum: 4 default: 1 augment_prompt: type: boolean default: true description: Rewrites your prompt behind the scenes into the form the model works best with. Leave it on (the default). Turning it off does not give you more control - it usually gives worse results. Do not disable it unless you really know what you are doing and have tested your prompts extensively. request_id: type: string description: 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: type: boolean default: true description: '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.' DirectionalPreview: type: object properties: direction: type: string description: The direction this preview is seen from. frame_urls: type: array description: The preview's frames as images, in order (one for a still model). Kept for 7 days. items: type: string width: type: integer height: type: integer num_frames: type: integer fps: type: number format: float render_3d: $ref: '#/components/schemas/DirectionalSpriteRender' DirectionalPreviewResult: type: object properties: previews: type: array description: One preview per direction, in the order asked. items: $ref: '#/components/schemas/DirectionalPreview' DirectionalSpritesResult: type: object properties: sheets: type: array description: One sheet per direction, in the order asked. items: $ref: '#/components/schemas/DirectionalSpriteSheet' PublicJob: type: object required: - id - task_type - status - created_at properties: id: type: string task_type: type: string description: 'The public operationId that created this job (e.g. createImage). Determines the shape of `result`: it is exactly the 200 response body documented for that operation.' status: type: string enum: - queued - running - succeeded - failed - canceled request_id: type: string created_at: type: integer format: int64 description: Unix ms finished_at: type: integer format: int64 credits_charged: type: number format: float description: Credits this job cost you. Charged at enqueue; reported as 0 once a job fails or is canceled, since the charge is refunded. result: type: object description: Present only when status is succeeded. Same shape as the synchronous response of the operation named by task_type. error: $ref: '#/components/schemas/PublicJobError' poll_after_ms: type: integer format: int32 description: 'Present while the job is queued or running: wait at least this many milliseconds before polling again. Prefer GET /assets/jobs/{id}?wait=30 (long-poll) over tight loops.' securitySchemes: ApiKey: type: apiKey name: Authorization in: header description: 'For accessing the API a valid API Key token must be passed in all the queries in the ''Authorization'' header. The following syntax must be used in the ''Authorization'' header: ApiKey xxxxxx.yyyyyyy.zzzzzz ' Bearer: type: apiKey name: Authorization in: header description: 'For accessing the API a valid JWT token must be passed in all the queries in the ''Authorization'' header. A valid JWT token is generated by the API and retourned as answer of a call to the route /login giving a valid user & password. The following syntax must be used in the ''Authorization'' header: Bearer xxxxxx.yyyyyyy.zzzzzz '