Omni Reference API - Kinovi 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

Standard (`seedance-20`)

Duration	Credits	Price	With 4K Upscale
4s	160	$0.80	272 credits ($1.36)
5s	200	$1.00	340 credits ($1.70)
8s	320	$1.60	544 credits ($2.72)
10s	400	$2.00	680 credits ($3.40)
15s	600	$3.00	1020 credits ($5.10)

Fast (`seedance2-fast`)

Duration	Credits	Price	With 4K Upscale
4s	112	$0.56	224 credits ($1.12)
5s	140	$0.70	280 credits ($1.40)
8s	224	$1.12	448 credits ($2.24)
10s	280	$1.40	560 credits ($2.80)
15s	420	$2.10	840 credits ($4.20)

Standard rate: 40 credits/sec. Fast rate: 28 credits/sec. 4K upscale: adds 28 credits/sec. Same pricing as Text-to-Video and Image-to-Video.1 credit = $0.005 (200 credits = $1).Fast mode generates videos ~2x faster with slightly reduced quality. Use seedance2-fast as the model value.

Authentication

Get API Key: API Key Management Page

Authorization: Bearer YOUR_API_KEY

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` (standard) or `seedance2-fast` (faster, lower cost)
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. Directly affects cost (40 credits/sec standard, 28 credits/sec fast).
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.
upscaleResolution	string	No	Set to `4k` to upscale the output to 4K resolution. Adds 28 credits/sec to the base cost.

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"
}

​What is Omni Reference?

​Use Cases

​Pricing

​Standard (seedance-20)

​Fast (seedance2-fast)

​Authentication

​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

Standard (`seedance-20`)

Fast (`seedance2-fast`)

Authentication

The `@` Reference Syntax

How It Works

Examples

Parameters

inputs

Reference Material Limits

Omni Reference vs Image-to-Video

Response

Status Values

Error Codes