Preview, select and export at a target FPS

Generate the source once

Create a video with /v1/video-generations and retain the video asset ID from outputs[]. Use it for metadata, previews and /v1/animation-exports. Changing the interval or FPS never requires regenerating the source motion.

Video assets returned by task polling and GET /v1/assets/{id} include media: measured duration_seconds, average source fps, decoded frame_count, display width and height. Unknown fields are null. Provider-requested duration and estimated counts are not substituted. Average FPS is not a frame locator for variable-frame-rate media.

New generated videos record a presentation timeline. Older videos are probed on demand by asset lookup, preview or FPS export. If reliable timing is unavailable, FPS export fails; the source can still be downloaded.

Inspect source timestamps

Send this to /v1/assets/{asset_id}/preview:

{
  "timestamps_seconds": [0, 1, 2, 3, 4],
  "max_frame_size": 256
}

Each timestamp must be in [0, measured duration). Duplicates and unsorted timestamps are supported. The response contains a labeled contact sheet in request order: image is a refreshable image asset, width and height are sheet dimensions, and cells[] contains index, requested_time_seconds, source_time_seconds and rect. Rectangles use top-left pixel coordinates and exclude labels.

Download image.download_url without API or OAuth credentials. Refresh an expired link by looking up image.id. Preview uses no AI, background removal or interpolation and does not represent final alpha quality.

Preview currently costs no credits. Cached images count toward account storage and follow normal asset retention, without a separate time-based expiration. Identical requests reuse an available preview.

Export an interval at FPS

First send this request to /v1/animation-exports/quote. Review the credits and resolved_export, then submit the same request to /v1/animation-exports with a new Idempotency-Key. Replace the example UUID with an owned video asset ID.

{
  "source_video_asset_id": "00000000-0000-4000-8000-000000000003",
  "selection": {"mode": "range", "start_seconds": 1, "duration_seconds": 2},
  "export": {
    "fps": 12,
    "output_formats": ["spritesheet", "spritesheet_json"],
    "output_width": 512,
    "output_height": 512,
    "transparent": {"enabled": true}
  }
}

Transparent exports still require an alpha_key source. This flag cannot remove an arbitrary background. Omit transparent when transparency is unnecessary.

The first FPS release requires both spritesheet and spritesheet_json; omitting formats selects this pair. Other combinations are rejected. Legacy frame-count exports retain existing format support.

Timing contract

• FPS samples at source playback speed. It is neither a speed control nor AI interpolation.
• For start S, duration T and FPS F, the interval is [S,S+T) and samples are S+i/F, excluding the endpoint.
• Count is ceil(T×F). Relative decimal serialization noise within 10^-12 of an integer frame boundary is absorbed; FPS input is not truncated.
• Samples select the source frame displayed at that presentation timestamp. resolved_export.warnings reports SOURCE_FRAMES_REPEATED when sampling repeats frames or exceeds the average source rate.
• Round cumulative playback boundaries to milliseconds using positive half-up rounding, then subtract adjacent boundaries. One second at 24 FPS yields 41/42 ms frame durations totaling 1000 ms.
• 1.1 seconds at 12 FPS yields 14 frames with a 17 ms final frame, totaling 1100 ms. The tail is neither dropped nor distributed across other frames.
• A tail quantized to 0 ms fails with TIME_PRECISION_UNSUPPORTED; adjust the interval.
• Aseprite JSON per-frame duration controls playback. meta.animgen.fps remains the requested sampling frequency. Nonuniform durations produce frameDurationMs: null.

Quotes and tasks use the same persisted sampling plan. Successful task resolved_export agrees with the manifest. Polling returns the resolved interval, FPS, count, total milliseconds and warnings, rather than every sample.

Limits, compatibility and recovery

Defaults: maximum 60 FPS and 240 frames, frame dimensions 64–1024 pixels, selection duration 0.1–15 seconds, sheet sides at most 8192 pixels and sheet area at most 67,108,864 pixels. Read the current schema and x-animgen-media-limits in OpenAPI for configured limits. Limits produce errors, never silently reduced FPS.

Preview supports up to 12 timestamps and 32–512 pixels per thumbnail side, with default limits of 4,194,304 output pixels and 10 MiB. Media probing/preview permits two simultaneous requests per service process, a 30-second media budget and at most five seconds for each download connection/read. Source limits are 256 MiB, 120 seconds, 18,000 decoded frames and 16,777,216 pixels per source frame. Busy capacity returns retryable MEDIA_BUSY; decoding timeout returns MEDIA_TIMEOUT. These budgets are configurable.

fps and frame_count are mutually exclusive. Omitting both retains the 24-frame default. Existing tasks and frame-count requests retain legacy sampling and selection tolerance. FPS requests reject out-of-bounds selections; full uses actual duration and requires a zero start with no supplied duration.

The one-click /v1/animations endpoint and MCP generate_animation remain frame-count workflows and reject FPS. Use staged generation followed by a quote against the existing source for FPS. Public API quotes do not lock prices and do not accept MCP-only quote_id or max_credits fields.

The same credential, idempotency key and request replay the same task. Change the key when changing interval/FPS. Replaying a failed task returns that failure; a corrected export uses a new key and the same source asset. Export cancellation or failure does not delete the source video.

Source videos have no separate time-based expiration field. Asset/task deletion and account policies still affect access; this is not a permanent backup guarantee. Signed URL expiration is independent of retention. Download long-term deliverables for safekeeping.

MCP equivalents

1. quote_video_generation → approved spend → generate_video → get_video_generation.
2. Retain the video asset ID; inspect media using download_asset and intervals using preview_video.
3. quote_animation_export → approved spend → export_animation → get_animation_export.
4. Download outputs and consume each manifest frame's duration.

Creation arguments quote_id/max_credits and idempotency_key are siblings of request. Quotes bind the operation type; export quotes also bind source asset, interval and export settings. Cancel with cancel_video_generation or cancel_animation_export, using task_id. Image upload uses the existing upload tools.