reference_video_urls.
Model
google/gemini-omni-flash-video-edit
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
reference_video_urls | string[] | Yes | - | Publicly reachable source video URL. Must contain exactly one URL. Uploaded source videos must meet the limits below. |
prompt | string | Yes | - | Edit instruction. Use @Video1 to refer to the source video and @ImageN/@CharacterN for extra references. |
reference_image_urls | string[] | No | - | Publicly reachable image URLs used as edit references. They count toward the total reference limit. |
reference_characters | array | No | - | Character references for the edit. Max 3 character items. Each character may include 1-10 image_urls. Supports per-character voice or custom_voice. See available voices. |
seed | integer | No | Random | Seed sent with the edit request. If omitted, a seed is generated automatically and returned when available. |
resolution | string | No | "720p" | Output resolution. Allowed: "720p", "1080p", "4k". With "1080p" or "4k", the edited video is upscaled as part of the same task before it completes — no separate upscale task needed. "720p" returns the native, non-upscaled output. |
start_frame | integer | No | 0 | First source frame index included in the edit range. |
end_frame | integer | No | Source end | Last source frame index included in the edit range. If omitted, the service uses the detected final frame when available. |
allow_audio_filtered | boolean | No | false | When true, the generation runs without audio instead of failing when the audio track is filtered. |
Limits
| Limit | Value |
|---|---|
| Video references | 1 |
| Character references | 3 |
| Total video + image + character references | 7 |
| Uploaded source video size | Up to 1 GB |
| Uploaded source video length | Up to 30 seconds |
Character References
Each character must be an object withimage_urls. Even one-image characters must use an array. Gemini Omni Flash edit also supports per-character preset voices and custom tuned voices.
Preset Voice
{
"image_urls": [
"https://example.com/character.png"
],
"name": "Ada",
"description": "warm, sharp, curious",
"voice": "achernar"
}
Custom Tuned Voice
{
"image_urls": [
"https://example.com/character.png"
],
"name": "Ada",
"description": "warm, sharp, curious",
"custom_voice": {
"voice": "achernar",
"name": "Ada voice",
"voice_performance": "calm, bright, expressive",
"sample_dialogue": "Hello, I am Ada.",
"speaker": "Ada"
}
}
| Field | Type | Required | Description |
|---|---|---|---|
image_urls | string[] | Yes* | Publicly reachable character image URLs. Use 1-10 images for a character entity. |
name | string | No | Display name for the character. Used as the temporary character handle/name. |
description | string | No | Character notes/personality text. |
voice | string | No | Preset voice for this character. Do not combine with custom_voice on the same character. |
custom_voice | object | No | Tuned voice config for this character. Use this instead of voice when you want to modify a base voice. |
custom_voice.voice | string | Yes | Preset voice used as the base voice for tuning. See available voices. |
custom_voice.name | string | Yes | Display name for the tuned voice. |
custom_voice.voice_performance | string | Yes | Direction for the tuned voice delivery, such as tone, energy, accent, pacing, or acting notes. |
custom_voice.sample_dialogue | string | Yes | Sample line used for tuning. Max 120 characters. |
custom_voice.speaker | string | No | Speaker label for the tuned voice. Defaults to the custom voice name when omitted. |
image_urls must contain at least one URL.
Example
curl -X POST https://api.unifically.com/v1/tasks \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "google/gemini-omni-flash-video-edit",
"input": {
"reference_video_urls": [
"https://example.com/source-video.mp4"
],
"prompt": "Make @Video1 look like it was filmed underwater, and replace the main person with @Character1.",
"reference_image_urls": [
"https://example.com/underwater-style.png"
],
"reference_characters": [
{
"image_urls": [
"https://example.com/ada-front.png",
"https://example.com/ada-profile.png"
],
"name": "Ada",
"description": "confident explorer",
"voice": "achernar"
}
],
"seed": 4734,
"start_frame": 0,
"end_frame": 122,
"resolution": "1080p"
}
}'
Prompt References
| Token | Refers to |
|---|---|
@Video1 | The source video for edit requests |
@Image1, @Image2 | Items from reference_image_urls only |
@Character1, @Character2 | Items from reference_characters only |
Rejected Combinations
| Input | Why rejected |
|---|---|
task_id | Edit requests must use reference_video_urls; source task IDs are not supported. |
Missing or empty reference_video_urls | An edit needs exactly one source video URL. |
More than one reference_video_urls item | Video edit accepts one source video. |
end_frame lower than start_frame | Frame range must move forward. |
| More than 7 total video + image + character items | Gemini Omni Flash edit reference limit. |
image_url on a character | Use image_urls instead, even for one image. |
| Plain string character entries | Character entries must be objects with image_urls. |
Empty image_urls | A character needs at least one image. |
More than 10 image_urls on one character | Character entity image limit. |
voice and custom_voice on the same character | Use a preset voice or a tuned voice, not both. |
Response
{
"code": 200,
"success": true,
"data": {
"task_id": "abc123def456",
"status": "processing"
}
}