Seedance 2.0 Omni Reference API

Generate videos that visually match your reference materials — images, videos, and audio. Perfect for character consistency, style transfer, audio-synced scenes, and scene continuity.

What is Omni Reference?

Unlike standard Image-to-Video (which animates an image), Omni Reference uses your uploaded materials as creative guides. The generated video maintains the look, identity, or style of your references without necessarily using them as literal frames. You can combine images, videos, and audio as references in a single request.

Use Cases

Use Case	Description	Example
Character Consistency	Keep a character’s appearance consistent across multiple videos	Provide a character portrait, generate different scenes featuring that character
Style Transfer	Apply the visual style of an image to a new video	Provide an art style reference, generate a new scene in that style
Scene Continuity	Generate videos that visually match existing content	Provide a scene screenshot, generate a continuation
Audio-Synced Video	Generate video synchronized to reference audio	Provide a music clip or voice recording, generate matching visuals
Multi-Modal References	Combine images, videos, and audio for richer control	Provide a character image + a motion video + background music

Pricing

Resolution	Pro (`seedance-20`)	Fast (`seedance2-fast`)
1080p (default)	83 cr/sec	—
720p	40 cr/sec	28 cr/sec
480p	15 cr/sec	10 cr/sec
4K Upscale	+28 cr/sec	+28 cr/sec
Video input surcharge (1080p)	+17 cr/sec	—
Video input surcharge (720p)	+8 cr/sec	+6 cr/sec
Video input surcharge (480p)	+4 cr/sec	+3 cr/sec

Video input surcharge applies when urls contains video files (MP4). It is per output second, added on top of the base rate. Example: A 5s Pro 720p video with a reference video = (40+8) × 5 = 240 credits. See Pricing for full plan comparison.

The `@` Reference Syntax

Use @image1, @video1, @audio1 etc. in your prompt to reference uploaded materials by position. This tells the model exactly where and how to use each reference.

How It Works

"urls": ["https://example.com/person.jpg", "https://example.com/dance-clip.mp4"],
"audioUrls": ["https://example.com/music.mp3"],
"prompt": "@image1 performs the dance moves from @video1, synced to the beat of @audio1"

@image1, @image2 → references images by position in the urls array (images only)
@video1, @video2 → references videos by position in the urls array (videos only)
@audio1, @audio2 → references audio files by position in the audioUrls array
If you don’t use @ syntax, the first image/video/audio is automatically used as the primary reference

The @ syntax is case-insensitive — @image1, @Image1, @VIDEO1, @Audio1 all work the same way.

Examples

Prompt	Behavior
`"A person @image1 walking on the beach"`	Uses the 1st image as the character reference
`"@image1 and @image2 having a conversation"`	Uses both images as character references
`"@image1 performs the moves from @video1"`	Character from image, motion from video
`"A scene synced to the rhythm of @audio1"`	Video synced to the audio reference
`"A beautiful sunset landscape"` (no @)	First reference is automatically prepended

Parameters

Parameter	Type	Required	Description
model	string	Yes	`seedance-20` (seedance2.0-pro) or `seedance2-fast` (seedance2.0-fast)
callBackUrl	string	No	Webhook URL to receive task completion notification
inputs	object	Yes	Generation parameters (see below)

inputs

Parameter	Type	Required	Description
urls	array	Yes	Reference image and video URLs. Can include images (JPEG, PNG, WebP) and videos (MP4). Must be publicly accessible URLs. Use `@image1`/`@video1` in prompt to reference them.
audioUrls	array	No	Reference audio URLs. Up to 3 audio files (MP3, WAV, etc.). Use `@audio1` in prompt to reference them.
prompt	string	Yes	Video description using `@image1`, `@video1`, `@audio1` etc. to reference uploaded materials. Max 4000 characters.
duration	string	No	Video length in seconds: `"4"` to `"15"`. Defaults to `"5"` if omitted.
aspectRatio	string	No	Aspect ratio: `16:9`, `9:16`, `1:1`, `3:4`, `4:3`, `21:9`. Defaults to `16:9`.
mode	string	Yes	Must be `reference` for Omni Reference mode.
outputResolution	string	No	Output resolution: `1080p` (default), `720p`, or `480p`.
upscaleResolution	string	No	Set to `4k` to upscale the output to 4K resolution.

Reference Material Limits

Material	Max Count	Constraints
Images	9	JPEG, PNG, or WebP. Must be publicly accessible.
Videos	3	MP4 format. Each video max 15 seconds.
Audio	3	MP3, WAV, or other common audio formats. Total duration max 15 seconds.

Key differences from Image-to-Video:

mode must be set to reference (not keyframe)
Images and videos are used as creative references, not literal video frames
prompt is required and should describe the desired video scene
audioUrls is only supported in reference mode

Omni Reference vs Image-to-Video

Feature	Image-to-Video	Omni Reference
Purpose	Animate an image into video	Generate video matching reference style/identity
Image usage	Literal first/last frame	Visual style guide
Video references	Not supported	Up to 3 videos (MP4, max 15s each)
Audio references	Not supported	Up to 3 audio files (max 15s total)
mode parameter	`keyframe` (default)	`reference` (required)
prompt	Optional (guides motion)	Required (describes the scene)
@ syntax	Not available	`@image1`, `@video1`, `@audio1`
Best for	”Make this photo move"	"Generate a new scene featuring this character”

Response

Status Values

Status	Description
`waiting`	Task queued, waiting to start
`generating`	Video is being generated (typically 1–3 minutes)
`success`	Generation completed, video URL available in `output`
`fail`	Generation failed, check `error` field for details

Error Codes

HTTP Status	Description	Common Cause
200	Success	—
400	Invalid parameters	Missing `urls` or `prompt`, invalid mode, invalid image URL
401	Authentication failed	Invalid or missing API key
402	Insufficient credits	Not enough credits for the requested duration
429	Concurrency limit exceeded	Too many tasks in progress, wait for some to complete
500	Server error	Internal error, retry later

curl -X POST https://kinovi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-20",
    "inputs": {
      "urls": ["https://example.com/character-portrait.jpg"],
      "prompt": "A person @image1 walking on the beach at sunset, cinematic lighting",
      "duration": "5",
      "mode": "reference"
    }
  }'

{
  "taskId": "task_clxxxxxxxxxxxxxx"
}

Video Models

Image Models

Seedance 2.0 Omni Reference API

What is Omni Reference?

Use Cases

Pricing

The `@` Reference Syntax

How It Works

Examples

Parameters

inputs

Reference Material Limits

Omni Reference vs Image-to-Video

Response

Status Values

Error Codes

Video Models

Image Models

Documentation Index

​What is Omni Reference?

​Use Cases

​Pricing

​The @ Reference Syntax

​How It Works

​Examples

​Parameters

​inputs

​Reference Material Limits

​Omni Reference vs Image-to-Video

​Response

​Status Values

​Error Codes

What is Omni Reference?

Use Cases

Pricing

The `@` Reference Syntax

How It Works

Examples

Parameters

inputs

Reference Material Limits

Omni Reference vs Image-to-Video

Response

Status Values

Error Codes