Omni Reference | Seedance2 API - AI Video Generation

Overview

Omni Reference mode uses images and videos as visual references to generate new video content. Unlike Image-to-Video mode where images become first/last frames, here materials serve as style, character, or motion references.

Audio is not supported. Generated videos do not contain audio tracks.

`@N` Prompt References

Use @1, @2, etc. in the prompt to reference specific uploaded materials. Materials are 1-indexed, with images first, then videos:

"A cat @1 dancing on @2 background" — references the 1st and 2nd material
When referencing an image, it is treated as an image reference; when referencing a video, it is treated as a video reference
@N where N exceeds the number of materials will be silently ignored
If no @ is used, materials are implicitly referenced via the material list

Example ordering — 2 images + 1 video: @1 and @2 reference images, @3 references the video.

Endpoint

POST https://seedance2-pro.com/api/v1/jobs/createTask

Headers

Header	Value	Required
Authorization	Bearer YOUR_API_KEY	Yes
Content-Type	application/json	Yes

Request Body

model

string

required

Must be seedance-20

inputs

object

required

Show inputs properties

urls

string[]

Array of publicly accessible image URLs used as visual references.In Omni Reference mode, images are not used as first/last frames — they serve as reference materials for character appearance, style, scene composition, etc.Image requirements: Max 10MB per image. Supported formats: JPG, PNG, WebP.

videoUrls

string[]

Array of video URLs for reference materials. Max 3 videos, each up to 50MB.Videos can be referenced using @N syntax in the prompt.

prompt

string

Text to guide the video generation.Supports @N syntax to reference specific materials (1-indexed, images first, then videos). Example: "This character @1 performs the dance from @2".

ratio

string

Aspect ratio for the output video. Options:

21:9 — ultra-wide
16:9 — landscape
4:3 — standard
1:1 — square
3:4 — portrait standard
9:16 — portrait

Defaults to 1:1 if not specified.

duration

string

default:"5s"

Video duration, from 4s to 15s

callBackUrl

string

Optional webhook URL for completion notification.

Credits

Duration	Credits	Cost
4s	160	$0.80
5s	200	$1.00
8s	320	$1.60
10s	400	$2.00
15s	600	$3.00

Formula: duration (seconds) x 40 credits

Example — Omni Reference with `@N`

Images with ratio — images serve as visual references, @1 @2 pin each to a role in the prompt.

curl -X POST https://seedance2-pro.com/api/v1/jobs/createTask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-20",
    "inputs": {
      "urls": [
        "https://seedance2-pro.com/landing/seedance2/cases/beat-sync/beat-sync-img-05.png",
        "https://seedance2-pro.com/landing/seedance2/cases/beat-sync/beat-sync-img-04.png"
      ],
      "prompt": "Scenic landscape images from @1 and @2, with beat-synced cuts between scenes, cinematic light shifts, and sweeping camera movements across the landscapes",
      "ratio": "16:9",
      "duration": "8s"
    }
  }'

Example — Character Consistency

Use a character reference image with ratio to keep the character consistent while generating new scenes.

curl -X POST https://seedance2-pro.com/api/v1/jobs/createTask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-20",
    "inputs": {
      "urls": ["https://seedance2-pro.com/landing/seedance2/cases/consistency/consistency-row1-ref.png"],
      "prompt": "This person @1 walking through a busy city street at golden hour, cinematic camera tracking shot",
      "ratio": "16:9",
      "duration": "5s"
    }
  }'

Example — Video Reference

Providing video materials automatically activates Omni Reference mode. The video is used as a motion/style reference.

curl -X POST https://seedance2-pro.com/api/v1/jobs/createTask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-20",
    "inputs": {
      "videoUrls": ["https://example.com/dance-reference.mp4"],
      "prompt": "Recreate this dance sequence in a neon-lit studio, matching the choreography and camera angles",
      "ratio": "16:9",
      "duration": "5s"
    }
  }'

Example — Image + Video Mixed Reference

Combine image and video references. Images are indexed first, then videos: @1 = image, @2 = video.

curl -X POST https://seedance2-pro.com/api/v1/jobs/createTask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-20",
    "inputs": {
      "urls": ["https://seedance2-pro.com/landing/seedance2/cases/consistency/consistency-row3-ref.png"],
      "videoUrls": ["https://example.com/action-reference.mp4"],
      "prompt": "This character @1 mimics the action from @2, smooth cinematic motion",
      "ratio": "16:9",
      "duration": "8s"
    }
  }'

Response

{
  "taskId": "task_clxxxxxx"
}

A 200 response means the task was created, not completed. Poll the Get Task Status endpoint to retrieve the generated video.

Get Result

Poll until status is success, then read the output array:

{
  "taskId": "task_clxxxxxx",
  "model": "seedance-20",
  "status": "success",
  "output": [
    {
      "url": "https://static.seedance2-pro.com/generated/video.mp4",
      "width": 1280,
      "height": 720
    }
  ]
}

See Get Task Status for full polling documentation.

Tips

Use @N in prompts to precisely control which material maps to which subject
Material ordering: images are indexed first, then videos. For 2 images + 1 video: @1 and @2 reference images, @3 references the video
Video materials: max 3 videos, each up to 50MB
If no @ references are used, materials are implicitly referenced — the model uses them based on the prompt context
For character consistency, provide a clear face/portrait image and reference it with @1
Video generation typically takes 1–10 minutes depending on duration and complexity

Omni Reference | Seedance2 API - AI Video Generation

Overview

`@N` Prompt References

Endpoint

Headers

Request Body

Credits

Example — Omni Reference with `@N`

Example — Character Consistency

Example — Video Reference

Example — Image + Video Mixed Reference

Response

Get Result

Tips

Next Steps

Image to Video

Text to Video

​Overview

​@N Prompt References

​Endpoint

​Headers

​Request Body

​Credits

​Example — Omni Reference with @N

​Example — Character Consistency

​Example — Video Reference

​Example — Image + Video Mixed Reference

​Response

​Get Result

​Tips

​Next Steps

Image to Video

Text to Video

Overview

`@N` Prompt References

Endpoint

Headers

Request Body

Credits

Example — Omni Reference with `@N`

Example — Character Consistency

Example — Video Reference

Example — Image + Video Mixed Reference

Response

Get Result

Tips

Next Steps