Seedance 2.5 Prompt Guide: The @ Reference Syntax

You upload three character images and a reference video into Seedance 2.5, write "reference @image1," hit generate — and the model puts the wrong face on the wrong body. That failure is almost never the model's fault: it's a syntax problem, and ByteDance's own practice guide spells out how to avoid it. This is the first systematic tutorial on the official @ reference syntax — how to bind up to 50 reference files (30 images, 10 videos, 10 audio clips) to specific roles so the output matches what's in your head.

Everything here is based on ByteDance's official Seedance 2.5 enterprise practice guide, cross-checked hands-on in Vogoo's studio — every spec and example prompt comes from that guide or ByteDance's public announcements. Seedance 2.5 officially launched on July 31, 2026, and the reference system is the biggest jump over 2.0: from 9 images and 3 short clips to a 50-file multimodal stack.

The one rule that fixes most broken Seedance prompts

The official guide's core prompt formula is simple:

Prompt = generation instructions (text) + reference materials (@Video N @Image N @Audio N)

The @ symbol "feeds" a material into the generation — @Image 1, @Video 1, @Audio 1 — and locks the corresponding visual or audio information.

Then comes the rule the guide states explicitly, and the one most people break. Paraphrased from the manual: every time you reference a material with @, immediately follow it with one sentence declaring how that material should be used. With multiple characters or multiple clips, you must spell out the mapping explicitly — otherwise the model gets confused. The guide even names the anti-pattern: a dangling "reference @Image 1" with no head and no tail.

Before — the dangling reference (what the manual warns against):

Reference @Image 1, reference @Image 2, generate an ad video

The model has no idea whether @image1 is the actor, the product, the scene, or the color grade.

After — every @ carries a usage declaration (official example):

Use the female lead in @Image 1 as the subject, and generate a video
of her strolling through city streets

One material, one job, stated in the same breath. Scale that discipline up and Seedance 2.5 keeps every face, prop, and scene where it belongs — the wuxia case below does exactly that with 32 references.

Seedance prompt syntax: the eight reference jobs

The practice guide breaks reference generation into sub-capabilities, each with its own declaration pattern. These official one-liners are worth keeping as templates:

Note the structure repeated in every row: @material + role verb + what it controls. That is the whole syntax — there is no markup beyond @; the binding lives in the sentence you attach to it.

Video editing and extension use a variant formula — edit instructions + @Video 1 (the source clip) + optional @Image N / @Audio N — where the model auto-locks aspect ratio and duration to the source. If you're coming from plain text-to-video or single-image image-to-video workflows, @ referencing is the layer that turns them into a controllable reference-to-video pipeline.

The 7 modality combinations

Seedance 2.5 accepts references in any of seven combinations — audio-only being new in 2.5:

Audio-only input is the combination to try first if you make music-driven content — a single track can drive rhythm, cuts, and mouth movement with no visual reference at all. It pairs naturally with an AI music video generator workflow, and voice-driven cases overlap with AI lip sync territory.

Reference material specs: what you can actually upload

The hard limits, straight from the practice guide:

Two details people miss: video and audio duration budgets are counted separately — up to 30 seconds of reference video and 30 seconds of reference audio in the same job. For context, Seedance 2.0 allowed 9 images and 3 clips each of video/audio with a 15-second total; 2.5 raises that to 30 images, 10 clips each, and 30-second totals.

How to ratio your references (section 2.3 of the guide)

Fifty slots does not mean you should fill fifty slots. The guide dedicates a section to what its team found through large-scale evaluation:

1. Avoid extreme clip lengths. A roughly 2-second reference clip carries too little information for the model to identify features reliably; a full 30-second clip dilutes the key features and adds noise. Aim for the middle of the 2-30s range.
2. Five subjects is the multi-view threshold. With 5 or fewer subject images, single-view or multi-view sheets both work. Past 5 subjects, single-view per subject is more stable — and if you need multiple angles of one subject, upload them as separate images rather than one collage containing several views.
3. When you're overloaded, cut in priority order: core characters first, then key products/props, then scene environment, then overall style references.
4. Know what counts as a "subject." The guide defines it as any core element the model must render consistently across the clip. In "a person in a forest shoots a rabbit with a bow," the person, the bow, and the rabbit are three separate subjects, each needing stable references.

Want to test these rules without setting up anything? You can try Seedance 2.5 free on Vogoo — 30-second one-shot generation, up to 4K, native synced audio, and up to 50 references in one job, right in the browser.

Five official cases, from 1 reference to 32

These are ByteDance's own demos from the practice guide, with the actual prompts where the guide publishes them.

1. Multimodal reference: creative transfer plus asset lock

One reference video supplies the creative concept; four images lock the assets. The declaration for each is one clause long:

Reference the creative concept of @Video 1; faithfully reproduce the full
house-assembly process using @Image 1 @Image 2 @Image 3 @Image 4.

Official Seedance 2.5 demo — ByteDance / Volcano Engine practice guide; prompt translated from the official guide.

Notice the structure: not just the reference images' appearance, but the build logic from the reference video is carried over.

2. Full-modality reference: one subject across many scenes

The guide's pomegranate showcase demonstrates why multimodal referencing exists: one subject travels through multiple scenes with form and style locked, because the reference stack — images, video, audio together — defines it once for the whole generation.

Official Seedance 2.5 demo — ByteDance / Volcano Engine practice guide.

3. The 32-references wuxia ensemble

This is the stress test: 32 references — character images, prop images, scene images, sound-effect clips, and an effects reference video — bound segment by segment with timestamps. An excerpt of the official prompt:

[0-3s] Close-up shot: the camera focuses on the hands of @Image 1 plucking
the strings of the guqin @Image 2. On the left, a bronze incense burner
@Image 3 trails wisps of smoke. In the background, the blurred figure of a
white-robed man @Image 4 is playing @Image 5. Sound effects reference
@Audio 1. The scene is set on a small boat @Image 7 on the water @Image 6,
with the distant mountains referencing @Image 8.
[3-5s] The white-robed man @Image 4 stands at the bow... the woman from
@Image 9 attacks wielding @Image 10; sound effects reference @Audio 2.
[5-10s] The white-robed man and the red-clad woman clash fiercely in the air
above the lake; sound effects reference @Audio 3. The red-clad woman holds a
red umbrella, the man holds the fan @Image 11. The water below erupts in
huge ring-shaped waves; sound effects reference @Audio 4, VFX reference
@Video 1.

Official Seedance 2.5 demo — ByteDance / Volcano Engine practice guide. Prompt excerpt translated into English from the guide's original.

All 32 references obey the rule from the top of this guide: @ plus an immediate usage declaration — which is what keeps two dueling leads, their weapons, and four sound effects from bleeding into each other.

4. Group choreography with documentary realism

The guide also shows the syntax in English — the prompt language doesn't change the @ mechanics (Seedance 2.5 natively supports 10-plus languages). The street-dance ensemble prompt opens:

Create a 30-second video with realistic cinematic texture, 16:9 aspect ratio,
documentary street photography style, warm and everyday lifelike atmosphere.
Street scene environment references @image1: late-afternoon street corner,
red brick buildings, pedestrian zebra crossings, storefronts along the road,
soft directional afternoon sunlight, transparent natural color tones.

Official Seedance 2.5 demo — ByteDance / Volcano Engine practice guide.

Again: @image1 is followed immediately by a colon and a full declaration of what it controls — the environment, down to the light direction.

5. Concept film: keyframe references in a 30s one-shot

Keyframe referencing is the lightest use of the syntax — two images, two declarations:

Cinematic brand concept film. @Image 1 is the first frame: the frame sways
slightly, the camera gradually pushes in toward tree shadows rushing past
the window, faster and faster — hard cut to @Image 2, the speed suddenly
eases, and the camera drifts slowly forward along a stream amid birdsong
and blooming flowers.

Official Seedance 2.5 demo — ByteDance / Volcano Engine practice guide (prompt rendered in English from the guide's original).

What makes @ referencing different

Most video models condition on references implicitly: you attach one image and the model decides what it means. Seedance 2.5 makes the binding explicit and scalable:

That last cell is the honest caveat: the syntax shifts responsibility to you. Skip the usage declarations and 50 references perform worse than 5 well-declared ones.

Common prompt mistakes (and the fix for each)

1. The dangling @ — "reference @Image 1" with nothing before or after. Fix: attach a role in the same sentence, every time.
2. Unmapped multi-character casts — five actor images, no statement of who is who. Fix: explicit mapping per character, as in the guide's ensemble prompts.
3. Reference stuffing — uploading all 50 slots "just in case." Fix: cut by priority (characters, then props, then scene, then style).
4. Extreme clip lengths — 2-second fragments or full 30-second clips as references. Fix: mid-length clips with the key feature clearly visible.
5. Collage sheets for large casts — one image containing six characters. Fix: past 5 subjects, one single-view image per subject.
6. Mixing edit and reference formulas. Fix: reference prompts generate new footage from materials; video-to-video edit prompts modify @Video 1 and lock everything else.

FAQ

How do I reference an image in a Seedance 2.5 prompt?

Use the @ symbol with the material's index — @Image 1 — and immediately follow it with one sentence declaring its role, e.g. "Use the woman in @image1 as the lead character." The official guide states the model gets confused without the declaration.

How many reference files can Seedance 2.5 take?

Up to 50 in a single generation: 30 images, 10 video clips, and 10 audio clips. Video clips run 2-30 seconds each with a 30-second combined cap; audio has its own separate 30-second cap.

Can Seedance 2.5 generate video from audio only?

Yes — audio-only reference is new in 2.5. A music track, voice line, or sound-effect bed can drive the pacing, beat-syncing, and lip alignment of the generated video with no visual reference attached.

Why does Seedance mix up my characters?

Almost always because references were listed without role declarations, or a multi-character cast was uploaded without an explicit who-is-who mapping. Declare every @ reference and, past five subjects, use one single-view image per character.

Do Seedance 2.5 prompts work in English?

Yes. The model natively supports 10-plus languages including English, Chinese, Spanish, Japanese, and Arabic, and the @ syntax works identically in all of them.

What's the difference between a reference prompt and an editing prompt?

A reference prompt generates new footage guided by your materials (text instructions + @ references). An editing prompt feeds an existing clip as @Video 1, describes only the local change, and the model auto-locks the source's aspect ratio and duration.

The bottom line

The @ reference syntax is the real interface of Seedance 2.5 — the 30-second one-shots and 4K output get the headlines, but the 50-file reference stack is what makes outputs repeatable and directable. The whole system reduces to one habit: never write an @ without a declaration, and map every character explicitly once your cast grows. Ratio your materials by the guide's priority order instead of maxing out the slots, and you get the consistency the wuxia and ensemble demos show. The fastest way to build the habit is reps: open Seedance 2.5 on Vogoo — free to try, up to 4K, native synced audio, up to 50 references per job — start with one subject image plus one declared motion reference, and scale up from there.

Sources

• ByteDance Seedance 2.5 Enterprise Practice Guide (Lark wiki) — primary source: the @ syntax rule, reference specs, ratio guidance (section 2.3), and every case prompt quoted above (login required).
• Seedance 2.5 — One-take Creation, Flexible Referencing (ByteDance Seed blog) — official announcement: 30-image/10-video/10-audio reference stack, 30-second single-pass generation, July 31, 2026 rollout.
• Seedance 2.5 official page (ByteDance Seed) — product positioning: audio-video joint generation, reference understanding, extension support.
• Seedance 2.0 official page (ByteDance Seed) — baseline for the 2.0-to-2.5 reference-capacity comparison.
• ByteDance launches Seedance 2.5 video-generation model — TechNode — independent launch coverage confirming date, 30s one-shot, and reference counts.
• ByteDance Unveils Seedance 2.5 Video Model — The Information — business-press confirmation of the release.
• Seedance 2.0 — Wikipedia — background on the Seedance line and its February 2026 predecessor.
• ByteDance's Dreamina Seedance 2.0 comes to CapCut — TechCrunch — context on the Dreamina-Seedance branding and global distribution.
• Hollywood isn't happy about the new Seedance 2.0 video generator — TechCrunch — context on the model family's realism and reception.
• Doubao Seedance SDK tutorial — Volcano Engine Ark docs — the Ark platform documentation family where Seedance API access lives.

Note on sourcing: reference specs, the @ declaration rule, ratio recommendations, and all quoted prompts come from ByteDance's official enterprise practice guide (primary source above); launch facts are cross-checked against the Seed blog and independent media. Model API pricing for Seedance 2.5 has not been published at the time of writing, so this guide states none.