DEV Community: WesLin

Build Clean Animated GIFs From Sprite Sheets With ffmpeg

WesLin — Sun, 13 Sep 2026 11:28:07 +0000

TL;DR

If you point ffmpeg straight at your raw sprite frames, you get a bloated 611KB GIF that shimmers on every frame. You can fix both problems with a two-pass ffmpeg command that builds one shared palette:

# Step 1: Generate a single 64-colour palette across all frames
ffmpeg -i frame-%02d.png -vf "palettegen=max_colors=64:stats_mode=diff" -update 1 palette.png

# Step 2: Render the GIF using that palette with dithering disabled
ffmpeg -framerate 12 -i frame-%02d.png -i palette.png -lavfi "paletteuse=dither=none" run-cycle.gif

These two steps shrink your file size by 78%. But palette work only fixes half your problem. If your animation still jitters, your cut is the reason.

The size ladder: why palettegen matters

A standard GIF supports at most 256 colours. A raw image from a model holds about 48,000 colours across subtle shifts in your background.

When you export without a custom palette, ffmpeg picks a separate 256-colour map for every single frame. That makes your background flicker, and it blows up your file size.

Export method	File size	What changed
Even grid cut, default palette	611,294 bytes	The bloated baseline.
Sprite-aligned, default palette	241,987 bytes	Alignment alone cuts 60% of the byte weight.
Sprite-aligned, shared 64-colour palette	165,345 bytes	The shared palette removes another 31%.
4-frame sheet, aligned, shared palette	130,635 bytes	The final production build.

Setting stats_mode=diff tells ffmpeg to build the palette around the pixels that move between frames. Setting dither=none stops speckling on your flat pixel-art surfaces.

The math: why even grid slicing fails

Most developers slice sprite sheets by dividing the canvas into equal boxes. If your image is 1672 pixels wide with 4 columns, you expect each box to be 418 pixels wide.

We tested sheets from the GPT Image 2.5 generator across Flare and Sunburst checkpoints. We asked for a 1280x720 sheet, but every one came back at 1672x941 pixels.

Here's what your actual pixel offsets look like on the raw sheet:

Canvas width: 1672 px
Target columns: 4
Calculated cell width: 1672 / 4 = 418 px

Actual frame start positions (Flare 8-frame):
Frame 1: 145 px
Frame 2: 554 px (gap: 409 px)
Frame 3: 928 px (gap: 374 px)
Frame 4: 1295 px (gap: 367 px)

Drift on frame 4: 418 - 367 = 51 px off-centre

The characters don't sit on an even grid. The gap between frame starts shrinks from 409 pixels down to 367 pixels across the row.

If you slice by fixed 418-pixel steps, your character drifts 104 pixels sideways and bounces 48 pixels up and down. That's half the character's body width in drift.

Align on the baseline, not the cell

To get rid of the bounce, you need to ignore the canvas grid and measure the pixels directly:

Find each sprite's actual box inside the raw image.
Crop tightly to your sprite's edges.
Place each cropped sprite onto one shared canvas.
Centre the crop from left to right, and line up the bottom edge where the feet land.

Slicing approach	Horizontal drift	Vertical bounce	Result
Even 4x2 grid	104 px	48 px	Character slides and bounces constantly.
Bounding box, bottom-aligned (8 frames)	19 px	0 px	Vertical bounce drops to zero.
Bounding box, bottom-aligned (4 frames)	1 px	0 px	Character stays locked in place.

Lining up the feet eliminates the 48-pixel vertical hop entirely.

Why you should make 4 frames instead of 8

When you prompt for an 8-frame run cycle across two rows, the model duplicates poses.

We measured frame similarity using mean absolute difference (MAD), which scores the average per-pixel difference between two images. A low score means two frames are near copies:

Top frame 3 vs bottom frame 7: 4.95 MAD
Top frame 2 vs bottom frame 6: 5.62 MAD
Top frame 4 vs bottom frame 8: 5.73 MAD
Top frame 1 vs bottom frame 5: 7.21 MAD

Genuinely distinct animation frames score 12.36 MAD or higher. The second row of an 8-frame grid merely repeats the first row with minor errors.

On Sunburst sheets, the gaps between frame starts measured 400, 366, and 417 pixels. On Flare, the gaps measured 409, 374, and 367 pixels.

A single-row 4-frame sheet keeps your frame starts within 7 pixels of each other. Sprite widths on the 4-frame sheet varied by only 2 pixels (227 to 229 pixels), compared to a 39-pixel spread on the 8-frame layout.

The video model route vs direct cutting

You can also pass your raw sprite sheet into an image-to-video model like Seedance 2.0 Mini.

We tested this with our 4-frame sheet at 480p. The model produced an 864x496 video with 121 frames in 93 seconds.

Metric	Direct sheet crop	Video generation route
Generation compute cost	1x	about 19x
Frame control	4 exact approved frames	121 generated frames
Palette size per frame	64 colours	7,433 to 8,194 colours
Final GIF size	130,635 bytes	530,249 bytes
Baseline drift	0 px	3 px

The video route keeps your character stable, with just 3 pixels of drift across five seconds.

But the video model redraws your character on every single frame. You lose your clean pixel outlines, and the colour count multiplies by more than a hundred times.

How to make the raw sheet

To try these steps yourself, open the GPT Image 2.5 tool and pick your settings.

OpenAI positions Flare for fast runs and Sunburst for tasks where you need higher editing precision. The composer lets you set resolution tiers (1K, 2K, 4K) and aspect ratios from one menu.

Use this prompt to make your source frames:

A 2D pixel-art sprite sheet of one character: a green-hooded courier with a brown satchel, side view facing right, running cycle, 4 frames in a single horizontal row, evenly spaced with equal margins on a flat mid-grey background, identical character height, proportions and colour palette in every frame, crisp 1px outlines, limited 16-colour palette, no text, no frame numbers, no grid lines, no drop shadows, no background scenery.

Three limits will stay on the raw output:

Background colour values shift slightly between runs (such as RGB 122,121,122 vs 127,126,125), so don't use hardcoded hex keys.
Files download as JPGs without an alpha layer.
Two-row requests duplicate poses across rows.

You can run your prompts directly on GPT Image 2.5 on Seadanse with starter credits upon sign-up.

Workflow checklist

Apply this checklist when you build your next sprite animation:

Ask for 4 frames in a single horizontal row, not 8 frames in a grid.
Read your image dimensions from the file header instead of assuming your requested canvas size.
Crop around individual sprite boxes rather than using equal grid cuts.
Align each cropped frame to a common bottom baseline where the feet land.
Make a shared 64-colour palette with palettegen=stats_mode=diff.
Build your final GIF using paletteuse=dither=none.

We work on Seadanse, which runs GPT Image 2.5, and the tests in this post were run there.

Wan 3.0 API spec and the three reference arrays

WesLin — Thu, 10 Sep 2026 09:43:57 +0000

The landing page for Wan 3.0 promises "up to 20 reference assets", but the underlying API does not accept a single list of twenty items. It splits those inputs across three separate arrays, each with its own count, file type, and duration cap.

What one wan3.0-video request actually takes

The API uses a single model identifier, wan3.0-video, across every generation mode. The fields you include in the payload determine which mode runs:

prompt: Text string up to 20,000 characters describing the shot.
resolution: Output size, accepting 480P, 720P, or 1080P. The provider default is 1080P.
duration: Video length from 2 to 30 seconds, or -1 to let the model select the duration. Default is 5.
audio: Boolean controlling sound generation, defaulting to true. Sound generates in the same pass as the video frames rather than as a post-process.
generation_type: Processing mode flag, set to frame for frame-driven generation or reference for asset-conditioned generation.
image_urls: Array of image URLs for single-frame generation or reference images.
image_with_roles: Array of image objects containing URLs and explicit roles (first_frame, last_frame, or reference_image).
video_urls: Array of reference video URLs.
audio_urls: Array of reference audio URLs.
file_url: URL for one reference document, up to 100 MB and 50 pages.
link_url: URL for one public web page reference.
size: Output dimensions and aspect ratio.
seed: Integer seed for output repeatability.
nsfw_check: Content filtering toggle.
watermark: Watermark inclusion toggle.

Payload construction determines the generation mode. Passing two frames into image_with_roles triggers first-and-last frame interpolation. Passing a single image into image_urls with generation_type: frame runs standard image-to-video. Passing image URLs with generation_type: reference runs reference-conditioned generation.

The twenty is three arrays, not one

Alibaba groups reference handling under the name Omni-Creation. The advertised twenty-asset capacity is divided into three fixed buckets:

Group	How many	Other limits
Reference images	up to 10	20 MB each; JPG, JPEG, PNG, BMP or WebP
Reference video	up to 5 clips	1-15 seconds each, 15 seconds in total; MP4 or MOV
Reference audio	up to 5 clips	1-15 seconds each, 15 seconds in total; WAV or MP3

The total of 10 images, 5 video clips, and 5 audio clips makes up the advertised twenty. Because each category is isolated, you cannot submit 20 reference images or a single 20-second reference video.

References bind to prompt text using explicit tags: @Image1, @Video1, and @Audio1. The numeric index maps to the position of the asset inside its respective request array. The API also accepts standalone reference audio in audio_urls without any attached visual reference.

One code block that does the arithmetic

Pricing scales along resolution and duration tiers without offering audio discounts:

Resolution cost scaling (fixed duration):
  480p  = 1x  (baseline)
  720p  = 2x
  1080p = 4x

Duration cost scaling (fixed resolution):
  5s    = 1x  (baseline)
  30s   = 6x

Audio setting:
  audio: true  = 1x
  audio: false = 1x (disabling audio does not reduce cost)

Scaling a batch from 480p at 5 seconds up to 1080p at 30 seconds increases resource consumption by a factor of 24. You can calculate specific requirements using the Wan 3.0 cost calculator.

What we shipped through it, and what the clips showed

We tested the pipeline by sending four clips through the API at 480p, 16:9 aspect ratio, 5 seconds per clip, with audio enabled. Prompts were transmitted exactly as written.

Clip 1 structured the prompt using a five-element order: shot type, subject, action, lighting, and sound. The render delivered the ceramicist lifting the bowl from the wheel, low window light entering from the left, background studio elements in shadow, and a visible camera push-in.

Generated with Wan 3.0, 480p, 5 seconds, audio on, from the prompt above, unedited — 2026-09-05.

Clip 2 formatted scene ambience as active clauses rather than descriptor lists: rain striking the glass, sodium streetlights crossing the subject's face sequentially, interior lighting restricted to an overhead strip, and a locked-off camera position.

Clip 3 supplied two reference stills from Nano Banana 2 tagged as @Image1 and @Image2. The yellow jacket, dark hair, and bag strap mapped from the first image, while the magenta neon, fire escape, and wet ground mapped from the second. Because text-to-image calls retain no state between separate generations, the open-shutter reference still had to be created by editing the closed-shutter still directly.

Generated with Wan 3.0, 480p, 5 seconds, audio on, with two stills attached as @Image1 and @image2 — 2026-09-05.

A single reference test confirms that label binding functioned in this instance, but it does not isolate whether the model resolved the assets via the @Image tokens or via matching text descriptions like "the courier" and "the alley".

Clip 4 tested frame-to-video with defined start and end points. The initial frame showed a closed shutter, which raised across the runtime before settling on the final framing. An additional run on 2026-08-16 evaluated a full 30-second continuous shot at 1080p, executing an unbroken crane pull-back from a rooftop herb garden to a dawn skyline. Full prompt text and media outputs are documented in the Wan 3.0 prompt guide.

What our own front end does not expose

The interface on the Seadanse model page provides access to text-to-video and frame-to-video generation, durations from 4 to 30 seconds, three resolution profiles, six aspect ratio presets plus Auto, a 10,000-character prompt field, and native audio generation.

Certain API capabilities are omitted from the front end:

Duration minimum: The composer enforces a 4-second minimum rather than the API's 2-second limit due to a shared schema constraint across our interface layer.
Document parsing: The API accepts PDF and text files via file_url, which is not exposed in the web composer.
Web page parsing: The link_url input is not wired to the UI.
In-place video editing: Direct video transformation via API flags is omitted.
Upload constraints: While the upload panel lists accepted file extensions (JPG, PNG, WebP, MP4, MOV), it does not display the API's per-group quantity and duration limits.

A checklist for the next model API page you read

When evaluating a video model API from its documentation, check these five constraints before writing integration code:

Array segmentation: Verify whether multi-asset reference claims allow arbitrary file combinations or mandate fixed allocations across image, video, and audio arrays.
Per-array duration caps: Check if video and audio inputs have aggregate duration ceilings in addition to individual file limits.
Default resolutions: Check the default API resolution value, as provider defaults like 1080p will run at higher cost multipliers than baseline 480p settings.
Duration floors: Compare the documented API minimum length against front-end limits to identify where interface validation schemas diverge from underlying endpoints.
Weight availability: Verify if model weights are downloadable. For Wan 3.0, no public weights exist on Hugging Face; open checkpoints under Alibaba's organisation stop at Wan 2.2 releases such as Wan2.2-TI2V-5B-Diffusers.

The author works on Seadanse, which runs Wan 3.0.

Automating Google Sites: What Worked, What Failed, and What Cost a Rebuild

WesLin — Wed, 09 Sep 2026 17:44:00 +0000

We needed to publish a 2,921-word article into new Google Sites from a script as part of shipping a model comparison. There isn't an API for the current version of the editor, so we had to test every programmatic input path to find what actually persists.

Most injection methods failed immediately, and one failed silently after reporting success. Here's every route we tried, the exact way each one broke, and the final model comparison on Google Sites that came out the other end.

There is no API, and that is official

If you look for a REST endpoint or an official client library, you won't find one. As Google's own deprecation notice explains:

"Sites API is deprecated and might stop working at any time. Sites API can only access classic Sites. Sites API can't access the rebuilt version of Sites that was launched on November 22, 2016."

Both the changelog and the developer guide carry that exact banner. That means classic Sites had an API, but the rebuilt version from 2016 never got one. That leaves you with the live editor in a browser tab, and whatever you can make that browser do through automation.

What we tried, and what came back

We tested seven different routes against the live editor on 2026-09-09 and 2026-09-10.

Route	What came back
`document.execCommand('insertHTML', …)`	"This document requires 'TrustedHTML' assignment."
`new DOMParser().parseFromString(html, 'text/html')`	The same Trusted Types error.
Build the DOM under `trustedTypes.createPolicy(...)`, then `Range.insertNode`	Renders correctly. Autosave says saved to Drive. Gone on reload.
`navigator.clipboard.write([new ClipboardItem(...)])` from an eval	Never settles. No transient activation.
Synthetic `cmd+v` through CDP or an extension	Nothing happens.
`osascript` System Events `keystroke "v" using command down`	"osascript is not allowed to send keystrokes."
Typing, character by character, through the extension	Works, and persists.

The third row is the one that's genuinely dangerous. When you build DOM nodes under a trusted types policy and insert them with Range.insertNode, the page renders your content cleanly.

The editor shows 18,482 characters, 11 h2 elements, 10 h3 elements, and 11 links. The autosave pill at the top turns into a checkmark and reads "all changes saved to Drive."

Then you reload the tab. The canvas clears, and you're staring at 0 characters.

Nothing in that sequence tells you it failed. The reason it disappears is that Google Sites doesn't treat the DOM as its source of truth. It keeps an internal document model in JavaScript.

When you mutate the DOM directly, that mutation doesn't update the internal model. On the next reload, the editor renders the state of its internal model, which is completely empty.

The one route that works

The only approach that updates the document model and survives a reload is sending synthetic keystrokes through a browser automation extension. It simulates a user typing characters one by one. That works, but three specific behaviors will bite you along the way.

First, synthetic typing silently drops non-ASCII characters. We had an em dash inside the string "TL;DR —", and it showed up in the editor canvas as two plain spaces.

The console threw no errors, and the extension reported a clean run. You've got to normalise every string to ASCII before you start typing.

Second, typing "- " at the start of any line triggers a retroactive list format. The editor detects the markdown shortcut and turns the entire text box into a bulleted list, including every paragraph you typed before that line.

You can't just backspace out of it. The fix is to run a select-all command and toggle the list button twice to strip the formatting.

Third, adding hyperlinks needs careful handling. You apply a link by selecting the anchor text in the live document and pressing cmd+k. That opens a link dialog with two traps.

If you press Return inside the URL input, the editor doesn't submit the form; it types the URL directly into the document and replaces your selected anchor with a bare URL. You've got to click the input field and click the apply button with synthetic click events.

On top of that, the text selector matches the first occurrence of an anchor phrase. If that phrase appears twice on the page, the script links the wrong sentence while the document looks completely normal.

Headings worked through keyboard shortcuts, but they needed explicit pacing. Pressing cmd+alt+2 and cmd+alt+3 applied real <h2> and <h3> tags to the selected line.

But the editor needed about three seconds between events. When we fired heading shortcuts back to back in a single batch, only the first one took.

A code block

Here's the terminal log showing what each programmatic input returned during our tests.

$ node -e "…"                      # no API to call
> execCommand('insertHTML', …)     Error: This document requires 'TrustedHTML' assignment.
> new DOMParser().parseFromString  Error: This document requires 'TrustedHTML' assignment.
> trustedTypes.createPolicy(...)   ok
  ... build nodes, Range.insertNode
  editor shows 18,482 chars, 11 h2, 10 h3, 11 links
  autosave: "all changes saved to Drive"
  reload                           0 chars
> navigator.clipboard.write(...)   (never settles)
> key: cmd+v                       (no change)
> osascript keystroke "v"          Error: osascript is not allowed to send keystrokes.
> type("Disclosure: we own ...")   persists

Two things about the output that cost us a rebuild

Two structural quirks forced us to tear down and rebuild our published layout.

The first quirk is how Google Sites generates <title> tags. On a subpage, the <title> tag matches the page name you assign. On the home page, the <title> tag is always the site name, no matter what you name the root page.

We published our article at the site root first, and Google Sites threw the article's title tag away. The fix was opening the page menu (the ⋮ icon) and clicking "Duplicate page."

That moved the content to a subpage and let us set the subpage name and custom path in a single dialog, so we didn't have to retype anything.

The second quirk is how the editor handles images. A text box holds text only. Images live in separate layout blocks that you position by dragging, which means an image can't sit inside the paragraph it illustrates.

Even worse, uploading an image through the editor's file input crashed the client interface with a runtime error. That crash happened on a 1.7 MB PNG and an 89 KB JPEG, so it wasn't a file size limit. That part of the pipeline still needs a human operator.

The checklist

If you're asked to automate publishing into a closed WYSIWYG editor you don't control, run these checks before writing your script:

Check whether the editor uses an internal document model instead of the live DOM.
Reload the page right after synthetic DOM mutations to confirm that autosave actually wrote data to the backend.
Test whether synthetic keystrokes drop non-ASCII characters like em dashes without logging warnings.
Check whether markdown triggers like leading dashes reformat earlier text blocks retroactively.
Test whether modal dialogs accept keyboard Enter or need explicit mouse clicks on action buttons.
Test heading shortcut pacing to make sure rapid shortcut events don't get dropped.
Test file inputs directly to see if scripted file uploads crash the client app.

Disclosure: we build Seadanse, an AI video tool, and the page we were publishing is a model comparison on a site of ours.

Seedance 2.5 API: The Official Endpoint and 6 Gotchas

WesLin — Mon, 24 Aug 2026 08:43:04 +0000

Three sites sell access to "the Seedance 2.5 API". Only one of them belongs to ByteDance. Here's the official endpoint, the model ID, and the six things that cost us time.

The official endpoint

ByteDance hosts the official API on BytePlus ModelArk. If you want to know which sites are actually ByteDance, check the domain on the endpoint before you write any code. Everything else selling a "Seedance API" is a reseller sitting in front of this.

You need an authorization bearer token and a JSON body to start a task:

curl -X POST https://ark.ap-southeast.bytepluses.com/api/v3/contents/generations/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "dreamina-seedance-2-5-260628",
    "content": [
      { "type": "text", "text": "A slow push-in on a red door at the end of a corridor, matching the light in @Image1." },
      { "type": "image_url", "image_url": { "url": "https://example.com/door.png" }, "role": "reference_image" }
    ],
    "generate_audio": true,
    "ratio": "16:9",
    "duration": 15
  }'

The model ID for Seedance 2.5 is dreamina-seedance-2-5-260628. If you pass the older Seedance 2.0 ID instead, you'll need dreamina-seedance-2-0-260128. You can confirm both IDs and the route directly in ByteDance's ModelArk docs.

The request body

The API takes a single JSON payload. Use these exact field names:

Field	Type	Default	What it does
`model`	string	required	the model id
`content`	object[]	required	the input list: text, images, videos
`omni_reference_task_type`	string	`auto`	task-type hint; marked new in the docs
`resolution`	string	—	output resolution
`ratio`	string	—	aspect ratio
`duration`	integer	—	seconds
`frames`	integer	—	frame count
`generate_audio`	boolean	`true`	makes the sound in the same pass
`watermark`	boolean	`false`
`output_format`	string	`mp4`	marked new in the docs
`seed`	integer	`-1`
`camera_fixed`	boolean	`false`
`return_last_frame`	boolean	`false`
`draft`	boolean	`false`
`service_tier`	string	`default`
`callback_url`	string	—
`execution_expires_after`	integer	`172800`	seconds, so 48 hours
`priority`	integer	`0`
`safety_identifier`	string	—	end-user identifier

Three defaults in this schema will surprise you if you don't check them:

generate_audio defaults to true — you'll generate sound tracks by default even if you only wanted silent video clips.
execution_expires_after defaults to 172800 — the docs call it the task expiration threshold, so that's 48 hours.
omni_reference_task_type defaults to auto — the system guesses your reference mode unless you tell it what task you're running.

Gotcha 1: your references are bound inside the prompt string

The content array holds text, reference images, and reference videos. The model takes up to 30 images, 10 video clips, and 10 audio clips in one call.

Instead of passing separate fields for character shots or motion guides, you point to your files directly inside the prompt string using @Image1, @Video1, and @Video2. ByteDance's own example prompt contains: "The strawberry flavor refers to @Image1" and "referring to the composition of @Video1" and "referring to the impact of @Video3".

The number after @Video or @Image counts against the order of items inside content. Nothing in the parameter table says this; the doc's example is the only place it appears. If you reorder items in content, @Video1 silently binds to a completely different clip.

Here's the minimal shape for a text prompt paired with an image reference:

[
  { "type": "text", "text": "A slow push-in on a red door at the end of a corridor, matching the light in @Image1." },
  { "type": "image_url", "image_url": { "url": "https://example.com/door.png" }, "role": "reference_image" }
]

Gotcha 2: the result URL dies in 24 hours

When a job finishes, the API returns a presigned URL (a link that carries its own expiry and signature in the query string) in content.video_url.

Look at the query parameters on that URL and you'll find X-Tos-Expires=86400. That's 86,400 seconds — so the link is dead in 24 hours, and anything you didn't copy is gone. If you save the URL in your database instead of copying the file, every video in your product's library is a dead link the next day, and nothing in the API tells you it happened. We copy every finished file to our own storage for exactly that reason.

Gotcha 3: audio is on unless you turn it off

The generate_audio setting defaults to true. That means the model makes synchronized sound in the same pass as the video frames.

So you'll get generated audio tracks even when your application only asked for background video. If your product adds its own soundtrack or needs silent video, you'll need to pass "generate_audio": false in your request body. If you leave the field unset, it won't be silent.

Gotcha 4: there is no 4K tier on 2.5

Don't build a 4K option into your UI for Seedance 2.5. The official ModelArk rate table lists only a 480p/720p tier and a 1080p tier for dreamina-seedance-2-5-260628.

4K exists on Seedance 2.0 (dreamina-seedance-2-0-260128), but it isn't available on 2.5. Several platform pages advertise 4K for 2.5 anyway. For example, a page titled "Seedance 2.5 API Now Available - 30s 4K AI Video on Kie.ai" mentions 4K in its title, but its own rate card lists only 480P, 720P, and 1080P.

Set your resolution to 480p, 720p, or 1080p. We haven't tested what a 4K request does on 2.5 — there's no tier to bill it against, so don't find out in production.

Gotcha 5: it is async, and the only thing you get back is an id

Task creation is strictly asynchronous. The API won't keep an HTTP connection open while the video finishes.

When you send a creation request, the only thing you get back is a task ID:

{ "id": "cgt-2026******-****" }

You have to poll the task endpoint to check the status:

curl -X GET "https://ark.ap-southeast.bytepluses.com/api/v3/contents/generations/tasks?page_size=3&filter.status=succeeded" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY"

When a task completes, the response gives you the full state:

{
  "id": "cgt-2026******-****",
  "model": "dreamina-seedance-2-5-260628",
  "status": "succeeded",
  "content": { "video_url": "https://ark-content-generation-ap-southeast-1.tos-ap-southeast-1.volces.com/...?X-Tos-Expires=86400&X-Tos-Signature=***" },
  "usage": { "completion_tokens": 108900, "total_tokens": 108900 },
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "framespersecond": 24
}

A finished task object carries several fields, but these are the ones that matter most for your app:

status — tells you if the job succeeded, failed, or is still running.
content.video_url — the temporary storage link to the generated MP4 file.
usage.completion_tokens — the exact token count you're billed on.

Billing runs per million tokens, and usage.completion_tokens is what ByteDance charges you for.

Gotcha 6: first-and-last-frame is a documented mode

The create-task documentation includes tabs for seven distinct modes:

multimodal reference (takes text, images, video and audio together)
edit video
extend video
audio video first frame
audio video first and last frames
image to video from base64
text to video

Worth knowing, because a wrapper only exposes the modes its authors wired up. If you need a clean transition between two states, first-and-last-frame is documented right there in ByteDance's own endpoint tabs — check whether the API you picked passes it through.

If you would rather not write the integration

If you want to run Seedance 2.5 in the browser without managing task queues, storage copies, and polling workers, you can use Seadanse. It takes reference images and reference clips for 5, 10, 15, 20, 25, or 30-second clips at 480p, 720p, or 1080p. It doesn't support reference audio, it has no video extension mode, and it caps at 1080p and 30 seconds. You can check what a clip costs directly on our pricing page.

Where these facts came from

Every parameter, endpoint path, and model name here comes from ByteDance's official documentation:

BytePlus ModelArk Task Creation, read 2026-08-21, page last updated August 18, 2026.
BytePlus ModelArk Task Polling and Retrieval, read 2026-08-21.
BytePlus ModelArk Pricing and Model IDs, read 2026-08-21.
ByteDance Seedance 2.5 Announcement, read 2026-08-21.

Is Seedance 2.5 free? I read every pricing page so you don't have to

WesLin — Fri, 21 Aug 2026 14:05:52 +0000

Landing pages for video models don't always match their buttons. When you look for Seedance 2.5, you'll find plenty of search results that claim free access. Most pricing pages treat "free" as a headline rather than a clear spec.

If you build things, you read pricing pages like API docs. You look for inputs, outputs, and hard limits. You don't want marketing copy when you're planning a build.

To see what's actually real, I checked every platform running Seedance on August 21, 2026 without an account. For each site, I treated the free tier as a spec with three fields: what the page claims, what it publishes as a number, and what you can make before giving up a card. When a number is missing, that missing number is the finding.

The state of free Seedance access

ByteDance built the Seedance family of models. Its own consumer tool is Dreamina (Dreamina). Dreamina's page is headed "Free Seedance 2.5 AI Video Generator with Audio". Its body says "Create cinematic 4K videos with Seedance 2.5 unlimited in Dreamina".

That same Dreamina page publishes no free-credit number anywhere. The tool behind it opens on AI image without an account. The video model list and any credit balance sit behind a sign-in box. You can't verify the grant without making an account first.

Other sites show similar gaps when you open them:

Seedance Studio publishes clear terms on its page (Seedance Studio). It lists a free plan of "160 credits/mo" and "Up to 3 videos or 20 images to try it out" at 480p with no card needed. In its own words, "Free videos use the same Seedance 2.5 model as paid plans, same quality, native sound and references. Not a stripped-down demo."
seedance.tv lists Seedance 2.5 in its model menu (seedance.tv). Its footer says "This platform is an independent product and is not affiliated with Bytedance." We checked its flow on August 13, 2026 and found its sign-up grant lands short of any Seedance 2.5 clip. You won't see its pack prices until you log in.
EaseMate AI titles its page "Create 30-Second HD Videos with Seedance 2.5 Free Online" (EaseMate AI). The on-page tool lists "Seedance 2.5 — Live Now". But its pricing page publishes no video allowance for the free tier (EaseMate AI Pricing). It says "Limited credits for images/videos" and gives 30 free credits on sign-up.
aiimagetovideo.pro titles its page "Unlimited Free Seedance 2.5 AI Video Generator by ByteDance (No Sign Up)" (aiimagetovideo.pro). A banner reads "Free Users Get 2 Daily Videos for AI Video Generator. Subscribers Get Priority Access." The generator on the page offers only one model, "Video Fast 1.0", at 3 or 5 seconds and 480p or 720p. It doesn't offer Seedance at all.
Luma runs Seedance 2.5 on its platform (Luma Labs). Its Plans & Pricing page lists only paid individual plans. It publishes no free plan at all.

Here's how each platform stacks up when you look at it without an account:

Platform	What a visitor with no account gets	Free Seedance 2.5?	What it means for you
Dreamina	Page says free and unlimited; the tool opens on images and the numbers sit behind sign-in	Not published	You have to sign in before you can find out what you were promised
Seedance Studio	160 credits a month, up to 3 videos, 480p, no card	Yes, capped	The clearest free route, if three 480p clips a month is enough
seedance.tv	Sign-up grant that lands short of one 2.5 render; pack prices after login	Not on the grant alone	You can look at 2.5 but you cannot finish a clip for nothing
EaseMate AI	30 credits on registration; the free video allowance is not published	Not published	The model is offered, the allowance is not written down
aiimagetovideo.pro	A generator with one model, Video Fast 1.0, and 2 videos a day	No — the page does not run Seedance	The page ranks for the phrase; the tool answers a different one
Seadanse	10 stills a day before sign-in, then 60 credits on sign-up with no card	Not on the grant alone	Free covers the rehearsal; you pay once for the take you keep

Sources: Dreamina, Seedance Studio, seedance.tv, EaseMate AI, aiimagetovideo.pro, Seadanse. Filled on August 21, 2026 by opening each page without an account.

The credit arithmetic on Seadanse

On Seadanse, you can test the setup before you spend anything. You don't have to guess what things cost.

Before signing in, you can make reference images. The composer's first step has a button labelled "Create visual". It works with no sign-up and lets you make up to 10 stills a day. Signed-in visitors also get 10 a day.

When you sign up with an email, you get 60 credits once. You don't need a credit card.

Credits are the site's own unit. Every video costs a set number of them. Here's the credit arithmetic for a new $0 account:

Sign-up grant (one-time, no card):           60 credits
Cost of one Mini clip (480p, 5 seconds):     60 credits
Balance after one Mini clip:                  0 credits

Cost of one 2.5 clip (480p, 5 seconds):     125 credits
Shortfall for Seedance 2.5 clip:             65 credits (60 - 125)

The composer opens on a 480p, 5-second Mini clip by default. That means you can press Generate once without changing any setting.

You'll always see the exact cost on the Generate button before you click it. If a run fails, the platform returns your credits automatically. You can check the ratios on the credit calculator.

Why debugging on Mini saves credits

You shouldn't debug prompts on an expensive checkpoint. Seedance 2.0 Mini and Seedance 2.5 come from the same model family. They take the same kind of written prompt.

Because both checkpoints share syntax, a prompt that reads correctly on Mini reads correctly on 2.5. You can read how to write a Seedance 2.5 prompt and run your tests on Mini first.

Mini runs at 480p and 720p. A 480p clip on Mini for 5 seconds costs less than half of what 2.5 costs at the same size and length (60 credits against 125).

That buys you a cheap rehearsal loop. You debug camera movement, framing, and action on the cheap checkpoint. Once the shot works, you switch the dropdown to 2.5 and pay once for the final take.

This ratio isn't unique to one site. Luma's published cost table charges Seedance 2.0 Mini at well under half the Seedance 2.5 rate at the same resolution (Luma Labs). The same ratio shows up across hosts.

What Seedance 2.5 runs in production

When you're ready for final output, the Seedance 2.5 AI video maker exposes the full model spec. You can check what Seedance 2.5 changed before setting up your run.

When you run Seedance 2.5 on Seadanse, you get:

Resolutions of 480p, 720p, and 1080p (there is no 4K on 2.5; 4K belongs to the Seedance 2.0 preset).
Lengths of 5, 10, 15, 20, 25, or 30 seconds.
Six aspect ratios: 16:9, 9:16, 1:1, 4:3, 3:4, and 21:9.
Sound made with the picture, on by default.
A prompt box that takes up to 10,000 characters.

Cost scales with duration. A 30-second clip costs six times a 5-second one at the same settings. If you need more credits, you can buy a $9.9 pack that does not need a subscription. Credits bought in a pack stay valid for 12 months.

To test your prompt on the default settings, open the composer and run your first rehearsal.

Checklist for evaluating video generation pricing pages

When you land on any page that promises free model access, run through these four checks:

Find the exact credit cost: Look for published numbers that show the credit price per clip length and resolution. If the number isn't there, you can't price your pipeline.
Check the actual model in the composer: Check whether the tool loads the model from the headline or swaps in an unrelated fast tier.
Compare the free grant to clip costs: Subtract the cost of one baseline clip from the sign-up grant. If the balance is negative, you can't finish a clip for free.
Check for standalone packs: See if the site sells simple packs like a $9.9 pack, or if it locks all usage behind a monthly subscription.

Disclosure: I work on Seadanse, one of the platforms in this comparison. Everything said about the other platforms comes from their own public pages, linked above.

I Built an Open-Source macOS Screen-Cleaning & Pet-Lock Utility in 3 Hours with AI

WesLin — Tue, 11 Aug 2026 05:16:09 +0000

The Problem Nobody Talks About

Here's a dumb problem that bugged me for years: I couldn't clean my MacBook screen properly.

Every time I grabbed a cloth to wipe the display, I'd accidentally brush the keyboard or trackpad. The screen would wake up, show my wallpaper, and suddenly I couldn't tell where the smudges were anymore. I'd end up "blind-wiping" and hoping for the best. Shutting down the whole machine just to wipe a screen felt absurd.

Then there was the cat problem. I saw complaints in App Store reviews: people watching videos on their Macs, and their cats would walk across the keyboard — pausing the video, switching tabs, opening Spotlight. Classic cat behavior, zero good solutions.

So I built CleanMyScreen.

What It Does

Three modes, one tiny app:

Mode	What Stays Visible	What Gets Locked
Cleaning	Pure-black overlay on all displays	Keyboard + pointer
Pet / Kid	Your current video or app	Keyboard + trackpad
Selective	Your desktop	Any combination you choose

Every session has a 3-second countdown before locking, an optional auto-timeout, and a 3-second Escape hold as an emergency unlock.

The Stack

SwiftUI for the UI
AppKit for window management and overlays
Core Graphics for display brightness control
IOKit for low-level HID device seizing (this is how you actually lock a specific trackpad vs. keyboard at the hardware level)

No Electron. No web views. No accounts. No telemetry. No network calls at all. The app literally cannot phone home.

Built in 3 Hours with Codex

Here's the part that still blows my mind.

I'd had this idea sitting in my backlog for over a year. It wasn't complicated conceptually, but between work and other projects, I never prioritized it — partly because the monetization path was unclear for something this simple.

Then I had some Codex credits about to reset, so I thought: why not just ship it?

The entire functional app was built in under 3 hours. Codex handled the SwiftUI views, the IOKit device enumeration, the overlay window management, and the brightness control logic. I spent the remaining time fine-tuning UX details — countdown animations, the emergency unlock flow, making sure device seizing was properly cleaned up on session end.

This is exactly the kind of project where AI coding tools shine: the requirements are clear, the scope is tight, and the individual pieces (IOKit APIs, CGDisplay functions) are well-documented but tedious to wire together manually.

Try It / Contribute

CleanMyScreen is MIT-licensed and works on both Apple Silicon and Intel Macs.

🔗 GitHub: github.com/opensource-works/CleanMyMac

You can build from source with just the Swift command-line tools — no Xcode project needed:

./Scripts/run-tests.sh
./Scripts/build-app.sh
open dist/CleanMyScreen.app

If you have ideas, bugs, or feature requests, open an issue. I'd especially love input on:

External display brightness control (it's best-effort right now due to macOS API fragmentation)
Additional use cases for the Selective mode
Localization — the app is English-only for now

htdemucs vs BS-RoFormer vs Spleeter: A 2026 Audio Source Separation Benchmark

WesLin — Wed, 29 Apr 2026 16:25:01 +0000

If you've spent any time looking at AI music separation in the last twelve months, you've probably run into the same three names: Spleeter, htdemucs (Hybrid Transformer Demucs), and BS-RoFormer. They show up in every comparison post, every research paper, and every "how to extract vocals" tutorial — but the way they're compared is usually wrong. Most posts cite a single SDR number from a 2019 paper and call it a day.

That's not useful if you're trying to ship a product, build a pipeline, or pick a model for real audio.

This post compares the three on the dimensions that actually matter when you're deploying audio separation:

Quality — SDR scores from peer-reviewed sources, not vibes
Inference speed — what you'll actually wait for in production
Cost per song — running on commodity GPUs at 2026 prices
Output flexibility — 2 stems vs 4 stems vs 6 stems
When each one is the right choice — and when it isn't

Everything below is based on published benchmarks plus our own production deployment of htdemucs at scale. Where we cite numbers, we cite the source.

TL;DR (for people who want the answer now)

Model	Best for	Output stems	Quality (avg SDR)	Speed
Spleeter	Real-time, low-resource, batch processing	2, 4, or 5	~5.9 dB (vocals)	~100× real-time on GPU
htdemucs	Production C2C apps, balance of quality and speed	4 or 6	~9.0 dB (avg)	~5–8× real-time on A40
BS-RoFormer	Highest-fidelity offline work, mastering, archival	4 (typically)	~9.80 dB (avg)	~2–3× real-time on A40

If you take only one thing from this post: htdemucs is the right default for almost any product, and you should probably be running htdemucs_ft rather than the default checkpoint. On Replicate's serverless pricing, all three Demucs variants (default, 6s, ft) cost essentially the same per call — but ft delivers meaningfully better separation. We didn't expect this when we started; it only became clear after looking at our actual billing.

BS-RoFormer is meaningfully better only on bass and only when latency doesn't matter. Spleeter is a 2019 model running on 2026 hardware — fast, but the quality gap is now audible.

The rest of this post explains why.

What we mean by "quality" — SDR explained briefly

Music source separation quality is usually measured in Signal-to-Distortion Ratio (SDR), in decibels. Higher is better. The reference dataset is MUSDB18 (or MUSDB18-HQ for high-quality audio), which contains 150 full-length tracks with isolated stems for vocals, drums, bass, and "other."

A few practical anchors:

<6 dB SDR: noticeable artifacts, "phasey" vocals, audible bleed between stems
6–8 dB SDR: usable for casual purposes (karaoke, learning songs, sketching ideas)
8–10 dB SDR: clean enough for content creation and most DJ applications
>10 dB SDR: approaching transparent for the average listener; suitable for release-quality work after light cleanup

Anything above ~9 dB on vocals is generally past the point where most listeners can tell the difference in a blind test. The gains from there are about edge cases — heavy reverb, doubled vocals, complex mixes.

A note on SI-SDR: Some recent papers report SI-SDR (scale-invariant SDR), which corrects for simple gain differences and is more robust. When numbers in this post differ from other sources, the metric definition is usually the reason.

The three models, briefly

Spleeter (Deezer, 2019)

Released by the Deezer research team in 2019, Spleeter is a U-Net architecture operating in the spectrogram domain. It comes in 2-stem (vocals/accompaniment), 4-stem (vocals/drums/bass/other), and 5-stem (adds piano) configurations.

It was a landmark release at the time — the first time anyone could run good-enough source separation on a laptop CPU without licensing fees. Six years later, it's been overtaken on quality by every modern model, but it remains the fastest and lightest option by a wide margin.

htdemucs (Meta AI, 2022)

The fourth-generation Demucs model from Meta AI's research team. Unlike Spleeter, htdemucs is a hybrid model — it operates in both the time domain (waveform) and frequency domain (spectrogram), with a Transformer backbone connecting them. The original paper reports a 1.4 dB SDR improvement over the previous Demucs generation on MUSDB-HQ.

Two variants matter in practice:

htdemucs — the standard 4-stem model
htdemucs_6s — a 6-stem variant that adds isolated guitar and piano stems

There's also htdemucs_ft, a fine-tuned version that's slower but slightly more accurate on individual stems.

htdemucs placed competitively in the 2021 Sony Music Demixing Challenge and remains the default for most production pipelines that aren't chasing the absolute SOTA.

BS-RoFormer (2023)

The current state of the art on MUSDB18-HQ, BS-RoFormer (Band-Split RoPE Transformer) is a pure-Transformer architecture that replaces RNN modules with a hierarchical RoPE Transformer. It splits the input spectrogram into multiple non-overlapping frequency sub-bands, exploiting the fact that different instruments occupy characteristic frequency ranges (bass low, cymbals high, etc.).

BS-RoFormer trained on MUSDB18-HQ plus 500 extra songs won first place in the Music Source Separation track of the Sound Demixing Challenge 2023 (SDX23). Even the smaller version trained without extra data reports 9.80 dB average SDR on MUSDB18-HQ.

The downside: it's slower and more memory-intensive than htdemucs, and the production-ready open weights are still scattered across community implementations rather than a single canonical release.

1. Quality benchmark (published SDR scores)

This is where most comparison posts fall apart — they cherry-pick a single number. Here are the per-stem SDR scores from the published literature, on MUSDB18-HQ (no extra training data unless noted):

Model	Vocals	Drums	Bass	Other	Average
Spleeter (4-stem)	~5.9 dB	~5.9 dB	~5.5 dB	~4.5 dB	~5.4 dB
htdemucs (default)	~8.1 dB	~8.4 dB	~8.6 dB	~5.9 dB	~7.7 dB
htdemucs_ft (fine-tuned)	~8.9 dB	~9.5 dB	~9.4 dB	~6.4 dB	~8.5 dB
BS-RoFormer (no extra data)	—	—	~11.28 dB	—	~9.80 dB
BS-RoFormer (with 500 extra songs)	—	—	—	—	~9.76 dB+

Sources: Spleeter scores from the Spleeter JOSS paper and the BeatsToRapOn separation benchmark. htdemucs scores from Hybrid Spectrogram and Waveform Source Separation and Benchmarks and leaderboards for sound demixing tasks. BS-RoFormer scores from the SDX23 results documented in the same paper.

A few observations from the table:

The Spleeter → htdemucs gap is bigger than the htdemucs → BS-RoFormer gap. Going from Spleeter to htdemucs gets you roughly +2.3 dB on average. Going from htdemucs to BS-RoFormer gets you roughly +1.3 dB. This is why htdemucs is the practical sweet spot for most use cases.

BS-RoFormer's biggest win is on bass. Bass separation jumps from ~8.6 dB (htdemucs) to ~11.28 dB (BS-RoFormer) — a difference you can hear in a blind test. The vocal and drum gains are smaller. If you're building something that specifically needs clean bass (DJ tools, transcription, music education for bass players), BS-RoFormer is worth the extra compute. For everything else, the gain is on the edge of perceptible.

htdemucs_ft is underrated. Many comparison posts only test the default htdemucs checkpoint. The fine-tuned version (htdemucs_ft) closes most of the gap to BS-RoFormer at the cost of roughly 4× the inference time — still faster than BS-RoFormer in practice.

2. Inference speed (real-world, not theoretical)

Approximate end-to-end time for a 3-minute song on a single A40 GPU, measured from API call to download-ready output:

Model	End-to-end time	Real-time multiplier
Spleeter (4-stem, GPU)	~2–5 seconds	~40–90× real-time
htdemucs (default, 4-stem)	~30–45 seconds	~4–6× real-time
htdemucs_6s (6-stem)	~40–60 seconds	~3–5× real-time
htdemucs_ft (fine-tuned)	~90–150 seconds	~1.2–2× real-time
BS-RoFormer	~60–120 seconds	~1.5–3× real-time

Notes:

End-to-end time ≠ pure GPU inference time. Public benchmarks usually report just the model forward pass on clean inputs. Real production time includes container cold start (5–30s on serverless), audio I/O (file download, ffmpeg pre-processing), and result upload. Our numbers above are end-to-end on Replicate.
Spleeter is in a different league for speed. It's the only one that runs comfortably faster than real-time on CPU alone.
htdemucs's overlap parameter is a big speed lever. The default overlap=0.25 is a reasonable trade-off; setting overlap=0.5 improves quality slightly at ~2× the cost; setting overlap=0 makes it noticeably faster but introduces audible chunking artifacts at segment boundaries.
BS-RoFormer's reference implementations vary wildly in speed depending on whose checkpoint and inference code you use. Numbers above are for the community-popular MVSep BS-RoFormer SW build.

If you're shipping a consumer product where users wait for results, anything slower than ~60 seconds for a 3-minute song starts to hurt conversion in our experience. That keeps htdemucs (default and 6s) inside acceptable territory and pushes htdemucs_ft and BS-RoFormer toward async/queued flows where the user can come back later.

3. Cost per song (production deployment economics)

This is the section where most online comparisons are completely wrong. Public pricing on Replicate looks straightforward — A40 at $0.000725/second, multiply by inference time, done. In practice, that calculation is off by roughly 2× from your actual bill, and there's a more interesting wrinkle that almost no comparison post mentions.

The headline finding from our production deployment

We've been running htdemucs in production at aistemsplitter.org for several months across all three Demucs variants — htdemucs (default 4-stem), htdemucs_6s (6-stem), and htdemucs_ft (fine-tuned). On Replicate's A40 GPU instances, all three variants cost approximately the same per call in our actual billing: roughly 22 calls per $1, or about $0.045 per song.

That's worth pausing on, because it contradicts what you'd expect from the published inference times.

Model	Naive cost (public pricing × inference time)	Our actual measured cost
Spleeter (GPU)	<$0.002	<$0.005
htdemucs (default)	~$0.022	~$0.045
htdemucs_6s (6-stem)	~$0.029	~$0.045
htdemucs_ft (fine-tuned)	~$0.11	~$0.045
BS-RoFormer	~$0.065	~$0.06–0.10 (varies)

Why all three Demucs variants converge to the same cost

The naive pricing model assumes you pay only for pure GPU inference time. In reality, every Replicate call also includes:

Container cold-start time (5–30 seconds when scaling from zero)
Model weight loading into GPU memory
Audio file download and ffmpeg pre-processing
Result encoding and upload back to storage
A minimum billable duration per call

These overheads are roughly fixed costs per invocation — they don't scale with how complex your model is. When the GPU forward pass goes from 30 seconds (htdemucs default) to 90 seconds (htdemucs_ft), the additional compute matters less to the bill than you'd expect, because the per-call overhead is already eating most of the budget.

The practical implication: if you're already on the htdemucs platform, there's almost no economic reason not to use the highest-quality variant your latency budget allows. If your users will wait 60 seconds, use htdemucs_6s (6 stems, default speed). If they'll wait 2 minutes, use htdemucs_ft (fine-tuned, near-BS-RoFormer quality on most stems). The bill is the same.

This is the opposite of the conclusion you'd reach by reading academic papers and Replicate's posted GPU pricing. It only shows up when you actually look at your bill at the end of the month.

Implications for unit economics

If you're modeling unit economics for a stem separation product, plan for $0.04–$0.05 per song as your floor, regardless of which Demucs variant you choose. That sets:

Free tier ceiling — at 10 free minutes per user (≈3 free songs), you're absorbing roughly $0.13 per signup before any conversion
Minimum viable credit pack pricing — anything below ~$0.10/song retail leaves no margin for Stripe fees, support, and infrastructure overhead
Bulk processing cost — at 10,000 songs/month you're looking at ~$450 in pure inference, before storage, bandwidth, and any other infrastructure

Two important caveats:

Cold starts dominate at low traffic. If your service is processing fewer than a few hundred songs per day, the cold-start overhead becomes proportionally larger. At very low traffic, the actual cost can drift up toward $0.06–$0.07 per song.
Self-hosting only beats this above ~$2k/mo in inference spend. Until you have enough sustained traffic to keep a dedicated GPU >40% utilized, serverless GPU is cheaper than RunPod, Vast.ai, or your own colo. We've measured this directly — Replicate stayed cheaper than dedicated infrastructure throughout our launch period.

4. Output flexibility (stem count and format)

Model	Available stem configurations	Notes
Spleeter	2, 4, or 5 stems	5-stem adds piano (separate model)
htdemucs	4 or 6 stems	`htdemucs_6s` adds guitar + piano
BS-RoFormer	4 stems (mostly); some 6-stem community builds	Quality drops on the rarer guitar/piano stems

This is where htdemucs_6s genuinely stands alone. If your use case requires isolated guitar or piano stems (music education, multi-track remixing, transcription), htdemucs_6s is the only widely-deployed model that delivers them at production quality. BS-RoFormer 6-stem variants exist in the community but are less mature; the canonical BS-RoFormer is a 4-stem system.

For "vocals only" or "instrumental only" use cases (the karaoke crowd), all three models work fine, and you should pick on speed, not quality. Spleeter at 90× real-time will give you a usable instrumental in milliseconds.

5. When to pick which one

After running these in production for several months, here's the simple decision tree we'd give someone starting from scratch:

Pick Spleeter when:

You need to process audio in real-time or near-real-time
You're running on CPU or constrained hardware
You need batch-processing throughput (e.g., feature extraction over a music catalog)
The quality bar is "usable" not "good"

Pick htdemucs when:

You're building a consumer-facing product where users wait <60 seconds
You need 6 stems (use htdemucs_6s)
You want the best quality-per-dollar ratio in production
You don't want to maintain custom inference code (it's well-supported on every major model-serving platform)

Pick BS-RoFormer when:

You're running offline or batch jobs where 1–2 minutes per song is fine
Bass quality specifically matters (DJ tools, transcription, audio analysis)
You're producing release-quality work and the marginal SDR matters
You're willing to invest engineering time in keeping up with community model releases

Don't pick any of these when:

You only need vocal removal for karaoke. Use Spleeter 2-stem; the quality difference doesn't matter for sing-along audio that's going to be played over a microphone.
You need real-time stem separation in a DJ application. None of these are real-time on consumer hardware. Use a DAW with built-in real-time separation (Ableton 12, etc.) or pre-process tracks offline.

What this looks like in practice

We run htdemucs_6s in production at aistemsplitter.org — a hosted version of 6-stem separation aimed at people who don't want to set up the local toolchain (which, between PyTorch versions, CUDA versions, and audio dependency hell, takes most people a full afternoon).

A few things we learned that aren't in the papers:

Real production cost is roughly 2× what naive calculations suggest, and roughly flat across Demucs variants. Public GPU pricing × inference time gives you a number that ignores platform overhead. Our actual Replicate bill works out to about $0.045 per song — and it's the same number whether we run htdemucs, htdemucs_6s, or htdemucs_ft. The fixed overhead per call swamps the marginal compute difference between models. This single fact changed how we think about model selection: pick on quality, not on theoretical compute cost, because the cost difference doesn't actually show up in your bill.
Format conversion matters more than the model. htdemucs only accepts WAV input. Users upload MP3, FLAC, M4A, OGG, and increasingly weird WebM containers. The pre-processing ffmpeg layer is non-trivial to get right at scale.
YouTube/SoundCloud URL ingestion is half the UX win. Asking users to download a file and upload it loses ~40% of them. Direct URL ingestion via yt-dlp is fiddly to maintain (age-restricted videos, region locks, livestreams) but worth it.
The 6-stem case is where users see the magic. When someone hears guitar isolated from piano on their favorite song for the first time, they tell their friends. The 4-stem case is "neat"; the 6-stem case is "wait, how is this possible".

If you want to hear what 6-stem htdemucs sounds like on real audio without setting up the toolchain, our site has free credits to try a few songs.

What's next in this space

A few open questions worth watching in 2026:

Will 8-stem (vocals/backing-vocals/drums/bass/guitar/piano/synth/other) become standard? Community fine-tunes are moving in this direction, but training data for individual synth and backing-vocal stems is the bottleneck.
Real-time on consumer hardware? No current open model runs at real-time speed on a CPU at acceptable quality. This will change with model distillation, but probably not in 2026.
Multilingual / non-Western vocal separation. Most published benchmarks are dominated by English pop and rock. We see noticeably lower performance on languages with different vocal techniques (Mandarin, Cantopop with heavy auto-tune, Bollywood vocal stacks). This is a genuine gap in the field, not a model deployment issue.

If you're working in this space and have data we'd find interesting — or you've hit something on these models we haven't — drop us a line.

References

htdemucs — Rouard, S., Massa, F., Défossez, A. Hybrid Transformers for Music Source Separation. arXiv:2211.08553
Demucs v4 (hybrid) — Défossez, A. Hybrid Spectrogram and Waveform Source Separation. arXiv:2111.03600
BS-RoFormer — Lu, W.-T., Wang, J.-C., et al. Music Source Separation with Band-Split RoPE Transformer. SDX23 Challenge results
Spleeter — Hennequin, R., Khlif, A., Voituret, F., Moussallam, M. Spleeter: a fast and efficient music source separation tool with pre-trained models. JOSS 2020
MUSDB18 dataset — Rafii, Z., Liutkus, A., Stöter, F.-R., Mimilakis, S. I., Bittner, R. The MUSDB18 corpus for music separation. Zenodo
Sound Demixing Challenge 2023 — Mitsufuji et al., SDX23 results
MVSep model leaderboard — mvsep.com/en/algorithms

Last updated: April 2026. If you find an error in the data, the SDR numbers, or any of the practical claims, send us a correction and we'll update the post with attribution.

Building a Kirkify AI Generator with Next.js and Google's Nano Banana Pro API

WesLin — Thu, 15 Jan 2026 08:05:14 +0000

How I turned a trending internet meme into a full-stack AI-powered web app (and why Nano Banana Pro is a game-changer for face manipulation)

If you've spent any time on Twitter or Reddit lately, you've seen them: the "kirkification" memes. Pictures of politicians, celebrities, or random people with Charlie Kirk's distinctively proportioned face seamlessly swapped onto them. They're hilarious, they're viral, and they're surprisingly hard to make well.

I wanted to create these memes. But every time I tried, I hit the same wall: manual face-swapping in Photoshop took 20+ minutes per image, online meme generators produced low-quality results, and I never quite nailed the subtle facial proportions that make a kirkification truly cursed.

So I did what any developer would do: I built Kirkify AI, a web app that generates photorealistic Charlie Kirk face swaps in seconds using Google's Nano Banana Pro API. Here's how I went from frustration to a working product, and why Nano Banana Pro turned out to be the perfect tool for this absurdly specific problem.

The Problem: When Memes Take Longer Than They Should

I wanted to create quality kirkification memes, but every approach had major drawbacks:

Option 1: Photoshop Manual Labor

15-20 minutes per meme masking, aligning, and blending
Required significant design skills
Results often looked fake despite the effort

Option 2: Existing Online Tools

Generic face-swap apps that didn't understand kirkification
Low-quality results with obvious cutout edges
Often watermarked or paywalled

Option 3: Manual AI Prompting (Midjourney, DALL-E)

Wildly inconsistent results
No reference image support for consistent likeness
AI didn't understand Charlie Kirk's specific proportions

The fundamental issue? A speed versus quality trade-off that felt impossible to resolve. I wanted a tool that could generate photorealistic kirkifications in under 30 seconds without requiring Photoshop expertise or AI prompting knowledge.

That's when I started looking into AI image APIs specifically designed for face manipulation, and that's how I discovered Nano Banana Pro.

Discovering Nano Banana Pro: The API I Didn't Know I Needed

My requirements were clear: handle face manipulation with high fidelity, support reference images (not just text prompts), process requests asynchronously, and deliver photorealistic results consistently.

I explored OpenAI's DALL-E, Replicate's Flux models, and Stability AI—all excellent for general image generation, but face-swapping is a specialized task requiring precise facial feature mapping and seamless blending.

Then I discovered Google's Nano Banana Pro. Here's what made it stand out:

Why Nano Banana Pro Won:

Face manipulation as core functionality - Not an afterthought, but engineered specifically for this
Native reference image support - Feed it Charlie Kirk's actual face for consistent results
Async callback architecture - Perfect for time-intensive operations
Photorealistic quality - Outputs indistinguishable from real photographs
Intelligent context preservation - Maintains hair, clothing, lighting, and backgrounds automatically
Granular facial proportion understanding - Actually understands facial geometry, not just overlaying faces

That last point was crucial. Charlie Kirk's face has very specific proportions that make the meme work. Nano Banana Pro understands facial geometry—the spatial relationships between eyes, nose, mouth—and maps them accurately while adapting to different angles and lighting.

Even complex costumes and comic book characters work flawlessly—Deadpool gets the full kirkification treatment

Building Kirkify AI: Tech Stack & Architecture Decisions

Tech Stack:

Next.js 16 (App Router) - Server-side rendering, API routes, React 19
TypeScript - Type safety for async operations and API contracts
PostgreSQL + Drizzle ORM - Track generation tasks and status
TailwindCSS + Radix UI - Fast, accessible UI components
Vercel AI SDK - Multi-provider support foundation

The Async Architecture Challenge:

Nano Banana Pro takes 10-30 seconds per face manipulation. I needed a system that could handle this without blocking the UI or timing out. Here's the flow:

User submits image → Frontend calls /api/generate-images
Backend creates task → Saves to database (status: "queued"), returns run ID
Backend calls Nano Banana Pro → Via APImart with callback URL, then moves on
Nano Banana Pro processes → Async on their infrastructure
Webhook receives result → /api/ai-callback/apimart updates database (status: "success")
Frontend polls status → /api/ai-task-status with exponential backoff (1s → 2s → 4s → 10s max)
User sees result → When polling detects "success" status

This webhook + polling hybrid gives real-time feedback without hammering the API. The exponential backoff keeps it responsive early on but backs off for longer operations.

I also built multi-provider support (OpenAI, Replicate, FAL) for flexibility and redundancy, though Nano Banana Pro became the star performer for face manipulation.

The Prompt Engineering Journey: Less Work Than Expected

I expected this to be the hardest part—getting AI to consistently understand "kirkification" while preserving context seemed like weeks of work.

Here's what actually happened: Nano Banana Pro just worked. After a few test runs, I landed on this prompt:

A photorealistic face swap based on this reference image.
Replace the face of the person in the image completely with
the face of Charlie Kirk. Capture Charlie Kirk's distinct
facial features, proportions, and likeness. Crucially,
maintain the exact original context: keep the same hair,
clothing, body pose, background setting, lighting conditions,
and film grain. Seamless blending, highly detailed,
realistic photograph.

That's it. No complex parameter tuning, no multi-step pipelines, no special case handling. This single prompt works reliably across all scenarios.

Why This Worked:

Natively understands facial geometry and proportions
Handles context preservation holistically without explicit per-element instructions
Performs seamless blending across different lighting conditions automatically
Renders photorealistic results without over-processing

Nano Banana Pro reduces complex face manipulation to a simple, descriptive prompt. The API handles the hard parts—facial geometry mapping, lighting adaptation, edge blending, context preservation.

The same prompt works across wildly different scenarios—Spider-Man in action

From superheroes to mech suits, consistent quality across all inputs

The Result: From Idea to Production

After integrating everything, I had a working product: upload any image, wait 20-30 seconds, and receive a photorealistic Charlie Kirk face swap.

The user experience is deliberately simple. Upload a photo, and within half a minute you get back a seamless face swap with no cutout lines, no weird blending artifacts, and the original context perfectly intact. Everything except the face—hair, clothing, background, lighting—remains untouched.

Here are some real examples:

A majestic lion gets the kirkification treatment—notice how Charlie Kirk's facial proportions are preserved while maintaining the original lighting and mane

Even complex facial expressions and professional photography lighting are handled seamlessly

Animals work particularly well—this fox demonstrates perfect facial proportion mapping

The results speak for themselves. These look like actual photographs that could plausibly exist.

Key Learnings:

Choosing the right API saves months - Nano Banana Pro's specialized capabilities eliminated the need to build face-swapping logic from scratch
Async architecture is essential - Quality face manipulation takes time; trying to force sync would cause timeouts and frustrated users
Invest in prompt templates upfront - One well-crafted prompt has powered thousands of generations with ~95% success rate
Multi-provider redundancy works - Fallback providers keep the app reliable during peak loads

Performance-wise: most generations complete in 15-25 seconds, and based on the increasingly cursed memes being created, user satisfaction is high.

Try Kirkify AI (and Let the Cursed Memes Begin)

Kirkify AI is live at ai-kirkify.com. Upload any photo—friends, celebrities, even pets—and watch the face-swapping magic happen.

For Developers:

The architecture patterns here—async callbacks, webhook handling, polling with exponential backoff—apply to any long-running API operations. If you're building with AI image generation or video processing, these patterns are broadly applicable.

Nano Banana Pro is accessible through APImart, an AI API marketplace. The documentation is clear, the API is straightforward, and the results deliver on the promise of photorealistic face manipulation.

What's Next:

I'm exploring batch processing for multiple images, style transfer options, and expanding to other viral meme formats. The multi-provider architecture makes adding new capabilities relatively painless.

The Takeaway:

Sometimes the best way to learn a technology is to build something absurd with it. Kirkify AI started as "I want faster Charlie Kirk memes" and evolved into a robust AI-powered web app with proper architecture and production-grade error handling. If you're curious about AI image generation, pick a ridiculous idea and start building. You'll learn more from shipping than from tutorials alone.

Now go forth and kirkify responsibly. Or irresponsibly. I'm not your boss.

Want to see the code or contribute? Check out the GitHub repository or try the tool at ai-kirkify.com.