Generate and Transform Sprites

Send JSON to POST https://www.spritefusion.com/api/v1/generate. Every accepted request returns an SSE stream.

Read the Agent Guide before using these operations.

Generate

Before using generate

• Describe one item or subject without requesting a number of outputs. The API returns variations automatically: use "Icons of a magic potion," not "15 icons of a magic potion."
• Ask for the subject or variations, not for a grid, contact sheet, atlas, or spritesheet that packs several assets into one image. "Make multiple boats" is acceptable; instructions such as "make a grid of 24 items" or a row-and-column layout are not.

{
  "operation": "generate",
  "prompt": "A clockwork fox carrying a brass lantern",
  "size": 32
}

size is 16, 32, or 64. The prompt limit is 10,000 characters.

curl -N https://www.spritefusion.com/api/v1/generate \
  -H "Authorization: Bearer $SPRITE_FUSION_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"operation":"generate","prompt":"A clockwork fox","size":32}'

Edit

Edits accept one to nine inputs. The first input is the primary sprite, and the result keeps its size: edit takes no size.

Before using edit

• State the requested change and anything important that should remain unchanged.
• Use the first input as the primary sprite and later inputs as supporting visual sources.
• Do not request a spritesheet containing several poses. Create each pose as a separate asset with edit instead.

{
  "operation": "edit",
  "prompt": "Give the hero from the first image the sword and shield from the other images",
  "inputs": [
    {"asset_id": "asset_hero"},
    {"data_url": "data:image/png;base64,..."},
    {"upload_id": "upl_large_reference"}
  ]
}

Style reference

Style reference accepts one to twenty images.

Before using style reference

• Describe the new subject and explain the role of each reference when it is not obvious.
• Use edit, not style-reference, when the goal is a targeted change that should preserve the primary image.
• Do not request a grid, contact sheet, atlas, or spritesheet that packs several assets into one image.

{
  "operation": "style-reference",
  "prompt": "A small forest shrine",
  "inputs": [
    {"asset_id": "style_1"},
    {"asset_id": "style_2"}
  ]
}

size is optional for style-reference and may be 16, 24, 32, 48, 64, 80, 96, 112, or 128. When omitted, Sprite Fusion infers the target from the size of the input sprites.

See Edit Your Pixel Art and Style Consistency for creative guidance.

8 directions

Before using 8 directions

• Provide exactly one source image.
• Do not write or send a prompt; direction-set has no prompt field.

{
  "operation": "direction-set",
  "inputs": [{"asset_id": "hero"}],
  "size": 32
}

This returns exactly eight directional sprites. See Generate 8 Directions.

Animate

Before using animate

• Make sure the source sprite has a pose suited to the requested motion. For walking, running, attacking, jumping, and similar actions, first use edit to create an appropriate starting pose, then animate that edited asset. Idle and other subtle animations can usually use the original sprite directly.
• Describe the motion, energy, and whether it should loop.
• Set frame and color counts with output_frames and colors, not in the prompt.
• Do not request a spritesheet layout in the prompt.

{
  "operation": "animate",
  "prompt": "A relaxed idle bounce, seamless loop",
  "inputs": [{"asset_id": "hero"}],
  "output_frames": 8,
  "colors": 24
}

output_frames may be any even number from 2 through 16. The animation prompt limit is 2,000 characters. The output asset includes assetUrl for the animation, sourceImageUrl, spritesheetUrl, frame count, and FPS.

See Animation Tips before animating a new source.

Tag results

Every operation accepts optional tags, saved on each output. The basic, recommended tag is the game or project name, such as dungeon-crawler. Add them when the user asks for it or names a group for the results, and reuse existing tags from GET /tags.

{
  "operation": "generate",
  "prompt": "A rusty iron sword",
  "size": 32,
  "tags": ["dungeon-crawler", "weapons"]
}

An asset has up to 10 tags. Each is 1–32 letters, numbers, spaces, hyphens, or underscores, and is stored trimmed and lowercase. See Organize results with tags.

Save generated files

Each output event contains a persisted Sprite Fusion asset. Download the returned asset.assetUrl into your project. Do not depend on hotlinking the hosted URL indefinitely; keep project-owned copies of files you ship.

Need Help?

Join the Discord