Skip to main content
POST

Authentication

string
required
All requests require Bearer Token authentication.Get an API key:Visit the API Key management page to get your API key.Add the following header when making requests:

Request Parameters

string
required
Video generation model name. Fixed as gemini-omni-1.2-flash-ext.
string
required
Video description or editing instruction. It cannot be empty after leading and trailing whitespace is trimmed. For Text-to-Video, describe the scene, characters, actions, camera, and sound; with images or videos, describe the motion, style, or changes you want.Example: "Aerial shot over a misty mountain lake at sunrise."
prompt is required in every mode, including first frame, multi-image reference, editing, and extension. A 400 error is returned if it is missing.
integer
default:"10"
Video duration in seconds. Must be an integer.
  • Text-to-Video / first frame / multi-image reference: output duration, 3–15
  • First and last frames: output duration, 3–10
  • Extension (extend): duration of the newly added segment, 3–10
  • Editing (edit): must not be passed; the output duration follows the source video
The alias seconds is also accepted. If both are passed, they must be equal.
Passing duration in editing mode returns a video edit does not accept duration error.
string
default:"720p"
Video resolution, case-insensitive. It determines the per-second price.Allowed values:
  • 360p
  • 720p
  • 1080p
  • 4k (2160p is also accepted)
Any other resolution returns a 400 error.
string
default:"16:9"
Only 16:9 (landscape, default) and 9:16 (portrait) are supported; other values return a 400 error.
string
Task type, specifying how the input material is used.Allowed values:
  • edit - Edit a video. Use with video_urls or extend_from_task_id
  • extend - Extend a video by appending new content at the end. Use with video_urls or extend_from_task_id
  • reference - Multi-image reference. Use with image_urls
  • text_to_video / image_to_video / reference_to_video - Text-to-Video / first frame / reference images
  • auto - Detected from the input; treated as edit when a video is provided
Optional when no video is provided; the mode is detected from the input.
When video_urls or extend_from_task_id is passed, a task type is required (omni_reference_task_type, or the compatible field generation_type); omitting it returns a 400 error. Passing edit or extend explicitly is recommended; auto is treated as edit.
string
Compatible field, equivalent to omni_reference_task_type. Allowed values: frame (same as image_to_video), reference, edit, extend.
generation_type and omni_reference_task_type cannot be passed together.
array<url>
Reference image array for multi-image reference (characters, products, styles, etc.). Supports 1–10 images.Only publicly accessible HTTP/HTTPS image URLs are supported. Upload local images first to get a public URL, then pass that URL; Base64 Data URLs are currently not supported and return a 400 error.When only 1 image is passed, how it is used depends on the task type:
  • omni_reference_task_type omitted: used as a reference image
  • omni_reference_task_type is auto or image_to_video: used as the first frame
For first-frame generation, use first_frame_image directly instead of relying on the number of images.
image_urls cannot be passed together with first_frame_image or last_frame_image, and images in image_urls are never treated as the first frame; images cannot be passed when editing or extending either.
string
First-frame image. The first frame of the generated video is this image. Only publicly accessible HTTP/HTTPS image URLs are supported; Base64 Data URLs are not supported.Passing it together with last_frame_image generates a first-and-last-frame video.
string
Last-frame image for first-and-last-frame generation; the video transitions from the first frame to this image. Only publicly accessible HTTP/HTTPS image URLs are supported; Base64 Data URLs are not supported.In first-and-last-frame mode:
  • duration supports 3–10; 10 seconds if omitted
  • system_prompt and negative_prompt cannot be passed
last_frame_image must be passed together with first_frame_image; passing only the last frame returns a last_frame_image requires first_frame_image error. It cannot be passed together with image_urls.
array<object>
Image array with roles, an equivalent way to write first_frame_image / last_frame_image / image_urls.
array<url>
Array of videos to edit or extend. Only 1 video is supported. You can also use the single-value field video_url instead; pass only one of them.Only publicly accessible HTTP/HTTPS video URLs are supported. Format: MP4 / MOV / WebM, up to 15 seconds and 64 MB.
When passing video_urls, a task type is required. omni_reference_task_type set to edit or extend is recommended (auto is treated as edit); omitting it returns a 400 error. Passing 2 or more videos returns a 400 error.
string
A task ID on this platform (task_01…). Continue editing or extending one of your previously completed gemini-omni-1.2-flash-ext tasks without re-uploading the video.Requirements:
  • The task belongs to the current account
  • The task model is gemini-omni-1.2-flash-ext
  • The task status is completed
  • The channel that generated the original task is still available; otherwise 503 source_channel_unavailable is returned
  • The original output is no longer than 15 seconds (applies to both editing and extension); in editing mode, its duration must also be detectable
If the channel is unavailable or the original output’s duration cannot be detected, download the original output and upload it with video_urls instead. If the original output is longer than 15 seconds, trim it to 15 seconds or less before uploading.
extend_from_task_id cannot be passed together with video_urls, and a task type is required. omni_reference_task_type set to edit or extend is recommended (auto is treated as edit).
string
Content you do not want to appear in the video.Example: "people, cars, color"
negative_prompt cannot be passed in first-and-last-frame mode.
string
System instruction, such as fixing the visual style or forbidding on-screen text. Must be a string.Example: "Render as a black-and-white silent film."
system_prompt cannot be passed in first-and-last-frame mode.

Response

integer
Response status code. Successful requests return 200.
array
Returned task array.

Query Task Result

Video generation is asynchronous. After submission, a task_id is returned. Use the Get Task Status API to query generation progress and results.
cURL
Poll every 5-10 seconds and set the client timeout to at least 10 minutes. Reference generation times (including queueing): about 46 seconds for a 15-second 360p video, about 99 seconds for 15-second 1080p, and about 4-5 minutes for 15-second 4k. Progress may stay at 10% for a long time until the task completes.

Successful Result Example

The video URL is data.result.videos[0].url[0]. data.actual_time is the task processing time in seconds, not the video length. The output is MP4 (H.264, 24fps) with an AAC audio track and an invisible SynthID watermark; 4k outputs occasionally have no audio track.

Failed Result Example

Failed tasks are fully refunded.

Billing

Billed per second: cost = per-second price of the selected resolution × billed seconds. All modes are billed at the requested resolution tier. See the pricing page for actual prices.

Use Cases

Scenario 1: Text-to-Video

Scenario 2: First-Frame Video

Scenario 3: First-and-Last-Frame Video

In first-and-last-frame mode, duration supports 3–10 seconds (10 seconds if omitted), and system_prompt / negative_prompt cannot be passed.

Scenario 4: Multi-Image Reference

Scenario 5: Video Editing

Do not pass duration when editing; the output duration follows the source video.

Scenario 6: Video Extension

Scenario 7: Extend an Existing Task

Scenario 8: System Prompt and Negative Prompt