Documentation

Animated Image Support

Check current still-image behavior and the planned path for preserving animation.

Read this page as markdown OpenAPI JSON Open docs search

Last updated: May 11, 2026

ImageGrid is still-image-first today. Use this page when your workflow depends on preserving animation instead of flattening to a still output.

Current default

Ordinary POST /v1/assets uploads now accept still-image jpeg, png, webp, gif, avif, heif, and jxl when the runtime can decode them.
For still-image resize and optimize, you can set an explicit output format. If you omit it, ImageGrid keeps the source format when that format is encodable and otherwise falls back to a safer output.
GIF and animated GIF inputs are handled as still images. Outputs are flattened to one frame.
Animated WebP is not part of the default upload path.

Planned support

Animated support is planned as an explicit capability rather than an automatic expansion of the default upload flow.

Planned direction:

make animated uploads an explicit opt-in
expose frame-aware details on animated assets, artifacts, and job results
preserve animation by default for animated resize and optimize
require explicit flattening for still-only outputs and tiled workflows

Planned response shape

Animated assets and animated derivatives will use a first-class response object instead of hiding frame state inside free-form metadata.

{
  "content_type": "image/webp",
  "width": 800,
  "height": 600,
  "animation": {
    "frame_count": 24,
    "frame_width": 800,
    "frame_height": 600,
    "duration_ms": 1200,
    "loop_count": 0
  }
}

The animation object is omitted for still assets and still artifacts.

Operation direction

Operation	Planned animated behavior
`resize`	preserve by default, flatten explicitly
`optimize`	preserve by default, flatten explicitly
`tile`	flatten required
`grid_render`	unchanged
`tile_patch`	unchanged

Resource policy

Animated inputs need additional controls beyond single-frame width and height.

Future policy work will cover:

frame-count caps
total animation duration caps
total decoded frame megapixel caps
frame-aware plan and billing rules

Current status

This extension is planned, not enabled. If your workflow needs animation preserved, contact ImageGrid before relying on the default still-image endpoints.