Seedance 2.5

Introduction

Reference is where generated video either holds an identity or drifts off it. One reference covers a talking head, and two or three cover most spots. Past that the model has to keep several faces, products, or voices stable at once, and that is exactly what Seedance 2.5 widens.

A single call takes up to 30 images, 10 videos, and 10 audio clips as references. You address each one in the prompt by its position in its array, @Image1 through @Image30, @Video1, @Audio1, and the model binds each reference to the role you give it. The three studio portraits below were cast into one band, each face locked to its own reference.

An editorial studio portrait of a lead singer in her late twenties with tousled auburn hair, warm hazel eyes, and a relaxed half-smile, wearing a faded vintage band t-shirt under a worn black leather jacket, three-quarter facing the camera on a warm off-white studio backdrop.

An editorial studio portrait of a guitarist in his early thirties with a short dark beard and a calm easy expression, wearing a charcoal denim shirt over a grey tee and a knitted grey beanie, three-quarter facing the camera on a warm off-white studio backdrop.

An editorial studio portrait of a drummer in his mid-twenties with close-cropped black hair, warm brown skin, and a bright open smile, wearing a heather-grey graphic t-shirt, three-quarter facing the camera on a warm off-white studio backdrop.

Each face came from its own studio portrait, and each one holds through the push-in. This guide covers the request shape, the @-tag addressing that binds references to roles, the kinds of reference the model reads across image and audio, and the count that different jobs actually need.

Request shape

References live under inputs, split by type. The task is videoInference, and the prompt does the binding.

import { createClient } from '@runware/sdk'

const client = await createClient({ apiKey: process.env.RUNWARE_API_KEY })
await client.connect()

const [result] = await client.run({
  model: 'bytedance:seedance@2.5',
  inputs: {
    referenceImages: [
      'https://example.com/vocalist.jpg',
      'https://example.com/guitarist.jpg',
      'https://example.com/drummer.jpg'
    ]
  },
  positivePrompt: 'A warm indie band performance on a small stage. The lead singer references @Image1 sings centre at the mic, the guitarist references @Image2 plays to her right, the drummer references @Image3 sits behind. Slow push-in as the chorus lands. Preserve each member\'s face, hair, and wardrobe from their reference.',
  resolution: '720p',
  duration: 8,
  deliveryMethod: 'async'
})

import asyncio
import os

from runware import Runware


async def main():
    async with Runware(api_key=os.environ["RUNWARE_API_KEY"]) as client:
        results = await client.run({
            "model": "bytedance:seedance@2.5",
            "inputs": {
                "referenceImages": [
                    "https://example.com/vocalist.jpg",
                    "https://example.com/guitarist.jpg",
                    "https://example.com/drummer.jpg"
                ]
            },
            "positivePrompt": "A warm indie band performance on a small stage. The lead singer references @Image1 sings centre at the mic, the guitarist references @Image2 plays to her right, the drummer references @Image3 sits behind. Slow push-in as the chorus lands. Preserve each member's face, hair, and wardrobe from their reference.",
            "resolution": "720p",
            "duration": 8,
            "deliveryMethod": "async"
        })


asyncio.run(main())

curl https://api.runware.ai/v1 \
  -H "Authorization: Bearer $RUNWARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "taskType": "videoInference",
      "taskUUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "model": "bytedance:seedance@2.5",
      "inputs": {
        "referenceImages": [
          "https://example.com/vocalist.jpg",
          "https://example.com/guitarist.jpg",
          "https://example.com/drummer.jpg"
        ]
      },
      "positivePrompt": "A warm indie band performance on a small stage. The lead singer references @Image1 sings centre at the mic, the guitarist references @Image2 plays to her right, the drummer references @Image3 sits behind. Slow push-in as the chorus lands. Preserve each member's face, hair, and wardrobe from their reference.",
      "resolution": "720p",
      "duration": 8,
      "deliveryMethod": "async"
    }
  ]'

runware run bytedance:seedance@2.5 \
  inputs.referenceImages.0=https://example.com/vocalist.jpg \
  inputs.referenceImages.1=https://example.com/guitarist.jpg \
  inputs.referenceImages.2=https://example.com/drummer.jpg \
  positivePrompt="A warm indie band performance on a small stage. The lead singer references @Image1 sings centre at the mic, the guitarist references @Image2 plays to her right, the drummer references @Image3 sits behind. Slow push-in as the chorus lands. Preserve each member's face, hair, and wardrobe from their reference." \
  resolution=720p \
  duration=8 \
  deliveryMethod=async

{
  "taskType": "videoInference",
  "taskUUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "model": "bytedance:seedance@2.5",
  "inputs": {
    "referenceImages": [
      "https://example.com/vocalist.jpg",
      "https://example.com/guitarist.jpg",
      "https://example.com/drummer.jpg"
    ]
  },
  "positivePrompt": "A warm indie band performance on a small stage. The lead singer references @Image1 sings centre at the mic, the guitarist references @Image2 plays to her right, the drummer references @Image3 sits behind. Slow push-in as the chorus lands. Preserve each member's face, hair, and wardrobe from their reference.",
  "resolution": "720p",
  "duration": 8,
  "deliveryMethod": "async"
}

[
  {
    "taskType": "videoInference",
    "taskUUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "videoUUID": "9c1b2d3a-4e5f-6789-abcd-ef0123456789",
    "videoURL": "https://vm.runware.ai/video/os/a14d18/ws/2/vi/9c1b2d3a-4e5f-6789-abcd-ef0123456789.mp4"
  }
]

The caps, and how they behave:

• inputs.referenceImages takes up to 30 images, each a URL, a data URI, or a UUID.
• inputs.referenceVideos takes up to 10 videos and inputs.referenceAudios up to 10 audio clips, each a URL or a UUID. The combined duration of the videos stays under 30 seconds, and the same for the audio.
• A UUID works for any of the three, image, video, or audio. It is either a previous generation's output or an asset you uploaded once through the Media Storage API to reuse across runs.
• The three pools share a single addressing scheme but count separately, so a call can carry the full 30 images alongside its videos and audio.
• positivePrompt is required, up to 10,000 characters, and it is where every reference gets its role.

The @-tag addressing convention

A reference is addressed by its position in the array, not its filename. The first image is @Image1, the second @Image2, on up to @Image30, and videos and audio number from one in their own pools as @Video1 and @Audio1. Two rules keep those pointers stable:

• Never address a slot you didn't pass. @Image11 in a call with ten images is a dead pointer, and the model quietly drops the clause that carried it.
• Rebind when you reorder. The address is the index. Move a reference from slot 3 to slot 5 and every @Image3 in the prompt now points at the wrong asset.

The reliable pattern is role binding: name a role, bind it to a reference, then refer to the role by name for the rest of the prompt.

The lead singer references @Image1.
The guitarist references @Image2.
The drummer references @Image3.

The lead singer sings centre at the microphone while the guitarist
plays to her right and the drummer keeps the beat behind them.
Preserve each member's face, hair, and wardrobe from their reference.

Role names are yours to invent, and the model treats each as a stable identifier for the referenced entity. When several subjects appear, list the mappings one by one rather than trusting the model to infer them. And bind identity in the prompt text, not inside the image: a name written on the reference picture is read as picture content, not as a label, so it tends to end up printed in the frame instead of naming the character.

The kinds of reference

Seedance reads more than appearance off a reference. Naming what a reference is for is what separates a clean result from a muddy one:

• Subject. The appearance or identity of a person, product, or scene. "Use the singer in @Image1 as the lead."
• Style. The look of an image or clip, its palette and grade. "Grade the shot in the cold teal night look of @Image1."
• Audio. Music, rhythm, a voice timbre, or ambience from an audio reference. "Match the beat and mood of @Audio1", or "give the narrator the voice timbre of @Audio1."
• Motion. Action, camera path, and pacing from a video reference, covered in the motion guide.

State the job for each reference, and if only part of an asset should carry over, say which part. "Use @Image1 for the wardrobe only" reads differently from "use @Image1 as the character."

Casting an ensemble

The higher cap earns its keep the moment a scene needs more than one anchored subject. One character reference is a solved problem. A full cast holding identity across a moving shot was not. The band shown at the top of this guide was cast from three portraits, one per member.

Every face in the performance resolves to its portrait, and the wardrobe holds as the camera moves. Bind each person to a distinct role name. Three portraits passed without role names collapse into an averaged ensemble where the model interpolates between the closest matches. singer references @Image1 and drummer references @Image3 give it a stable identifier per person that survives the push-in and any cut.

Assembling a product family

The same budget composes separately shot products into one staged scene. Before the higher cap, a set of packshots that lived alone became several generations plus a compositing pass. Now one call renders the composed shot. The three tech products below were each shot as an isolated packshot, then staged on one desk.

A pair of premium wireless over-ear headphones in matte off-white with soft grey ear cushions and a slim brushed-silver headband, at a slight three-quarter angle on a neutral off-white seamless studio backdrop, soft even overhead lighting.

A modern smartwatch with a rounded charcoal aluminium case and a soft sage-green woven sport band, screen dark, propped at a slight angle on a neutral off-white seamless studio backdrop, soft even overhead lighting.

A compact low-profile mechanical keyboard with warm cream and pale-grey keycaps in a slim aluminium frame, angled slightly on a neutral off-white seamless studio backdrop, soft even overhead lighting.

Each product keeps the exact colour and finish it had in its packshot. Address each one by its content, not just its index. @Image1 alone is a bare pointer, but "the matte off-white headphones reference @Image1" gives the model both the address and a description to hold to, so when a render starts to drift it has something to pull back toward.

Building from a single generated still

A reference can be a still you generated a moment earlier. For a hero shot where one frame has to look exactly right, it is faster to iterate the still in an image model and then hand it to Seedance as ground truth than to re-roll a whole video each time. The film still below was generated in an image model, and Seedance animated the moment around it.

A wide cinematic film still of a lone figure in a long charcoal wool coat standing at the far end of a weathered wooden pier over still glassy water at misty dawn, muted teal-and-grey palette, soft diffused light through low fog, a distant treeline across the water, the figure seen from behind and small in a wide frame.

The frame holds the composition and palette of the still while the fog, the water, and the figure come to life. A still iterates in seconds where a video takes minutes, so a strong single reference is often the fastest way to lock a hero look before committing it to motion. Pass it as inputs.referenceImages[0] when the composition can evolve. Pin it with inputs.frameImages when the still must be the literal opening frame, which the image-to-video guide covers.

Composing image and audio

Every reference so far has been an image, but the same call reads audio references too, addressed as @Audio1 next to @Image1. An audio clip hands the model a sound to build toward, a musical mood and tempo or a specific voice, so one request can carry an identity from a picture and a soundtrack or a voice from a clip.

A music reference scores the scene. Pass a track through inputs.referenceAudios, name it in the prompt, and the generated performance takes its mood and tempo with the motion settling onto the pulse. Below, a dancer cast from a single portrait performs to a reference score.

An editorial studio portrait of a contemporary dancer, a woman in her twenties with a lean athletic build and dark hair drawn back into a low bun, wearing a simple fitted charcoal-grey dance leotard, standing three-quarter to the camera in a relaxed neutral full-body pose on a plain warm off-white studio backdrop, even soft studio light.

Her identity comes from the portrait and the pacing of the piece follows the track. That is the difference between animating to a placeholder and generating straight to the sound you already have.

A voice reference works the same way for spoken delivery. Attach a voice clip, describe the visible speaker, and the model gives the speaker that voice with the lip-sync matched to it. Here a brand presenter cast from one portrait speaks in a generated reference voice.

An editorial studio portrait of a warm, confident brand presenter, a woman in her thirties with shoulder-length dark hair and an easy approachable smile, wearing a smart charcoal blazer over a white tee, head-and-chest framing facing the camera on a plain warm off-white studio backdrop, even soft studio light.

One face and one voice composed into a talking clip. Swapping either reference holds the other fixed, which is how a spokesperson keeps a consistent voice across many faces, or one face carries many voices across markets. The pools compose the same way the images did, so a single call can carry a full cast of portraits and an audio bed together, each held by its own tag.

How many references a job needs

The caps are ceilings, not targets. Stability falls off well before them, so match the count to what the shot actually has to lock:

• Image subjects hold well from 1 to 8. Nine to twelve can work, with lower stability and a few more attempts.
• Video or audio subjects are tighter: 1 to 5 is the reliable band, and 6 to 10 gets shakier.
• Keep each subject's video or audio reference short, roughly 5 to 10 seconds. Longer inputs cost stability.
• For more than five subjects, prefer a single clean view per subject. If a subject genuinely needs several angles, pass them as separate images rather than one collage, which the model reads as one busy picture.

The right number is however many identities the final shot has to keep fixed. Fewer references render faster and cost less. More of them make a dense ensemble possible and remove the compositing pass that used to sit between the packshots and the deliverable.

Tips

1. Address by index, describe by content. @Image1 is always the first entry in inputs.referenceImages. Pairing the tag with a short description ("the sage-band smartwatch reference @Image2") gives the model something to pull back to when a render drifts.

2. Give each anchored subject a distinct role name. singer references @Image1 survives camera moves and cuts. Without a role name, similar references average together and identifying detail slips.

3. Bind identity in the prompt, never inside the image. A name painted on a reference picture is read as picture content and tends to print in the frame. State the mapping in the prompt text.

4. Order the array by priority. The lowest-index references hold identity most consistently, so put the lead character or the hero product first and supporting elements after.

5. Close with a preservation clause. "Preserve the exact face, hair, and wardrobe of each subject from their reference" is what holds unmentioned detail steady through a move. Combine it with the @-tags rather than replacing them.

6. Keep references clean and isolated. A packshot on a neutral ground and a portrait on a plain backdrop resolve more reliably than a lifestyle photo, which drags its own background into the new scene.

7. Iterate a hero still in an image model, then animate it. When one frame has to look exactly right, generate it in an image model first and pass it as inputs.referenceImages[0]. A still iterates in seconds. A video does not.

8. Store repeat references as UUIDs. A campaign that reuses the same cast or product across many runs is lighter to send if the assets are uploaded once through the Media Storage API and referenced by UUID.