Skip to main content
POST
Text-to-video and image-to-video support 3–15 whole seconds, default 10. First/last-frame interpolation and the added segment of an extension support up to 10 seconds. Editing ignores duration and preserves the source video length. Video input defaults to editing; extension requires "omni_reference_task_type": "extend".

Authentication

string
required
Use Bearer token authentication. Get a key from the API Key management page. Submit requests with Content-Type: application/json.

Request parameters

string
required
Must be gemini-omni-1.2-flash.
string
required
Required text instructions: describe the scene for text-to-video, or the motion, style, or changes for image-to-video, editing, and extension. You must provide prompt even when supplying reference images, first/last frames, video, or extend_from_task_id. Omitting it returns HTTP 400.
integer
default:"10"
Output duration for text-to-video and image-to-video as an integer from 3 to 15, default 10. First/last-frame interpolation and extension support only 3–10 seconds. For extension, this is the added segment length; the returned video includes both the original and added segments. Editing ignores duration and preserves the source video length. Parameter values outside the allowed range fail the task with invalid_duration.
string
default:"720p"
360p / 720p / 1080p / 4k, case-insensitive; 2160p is treated as 4k. 1080p and 4k are upsampled. Resolution affects output token usage and the reserved amount. Other values fail the task with invalid_resolution.
string
default:"16:9"
Only 16:9 (landscape, default) and 9:16 (portrait). Other values are treated as 16:9.
string[]
Reference images as publicly accessible HTTP(S) direct image URLs only. Data URLs and Base64 are not supported. One image defaults to the starting frame; multiple images act as subject references. Up to 10 images in total, including first/last frames. For character references, use at most 2 characters with up to 3 images each, preferably no more than 6 images overall.
string
Starting frame. Used alone, generation starts from this image; with last_frame_image, it enables first/last-frame interpolation. Only publicly accessible HTTP(S) direct image URLs are supported.
string
Ending frame; requires first_frame_image, otherwise the task fails with invalid_frame_images. Use the same ratio for both frames and match aspect_ratio. Only publicly accessible HTTP(S) direct image URLs are supported.
object[]
Images with roles, an alternative to the direct first/last-frame fields. Choose one way to specify the frames. All images used count toward the total limit of 10.
string[]
Video to edit or extend: at most 1 clip, no longer than 15 seconds. Only publicly accessible HTTP(S) direct video URLs are supported. Data URLs and Base64 are not supported. Video input defaults to editing.
string
default:"auto"
Task type: auto (default, inferred from the input) / edit (editing) / extend (extension) / reference (multiple image references). Also accepts text_to_video / image_to_video / reference_to_video. When omitted or set to auto, both video_urls and extend_from_task_id default to editing; extension requires an explicit extend value.
string
Reference your own previous generation task ID to reuse its video without uploading it again. Defaults to editing. With "omni_reference_task_type": "extend", adds a segment of up to 10 seconds at the end.

Capabilities and limits

  • Output is 24fps video with dialogue, music, or sound effects. Describe the desired audio in prompt.
  • Audio input, system prompts, temperature, and negative-prompt parameters are not supported. Put negative instructions directly in prompt.
  • Upstream regional restrictions: in the EEA, Switzerland, and the UK, editing or extending uploaded videos and editing images containing minors are not supported.
  • All output contains an invisible SynthID watermark.

Examples

Submit each JSON body to POST /v1/videos/generations. Replace example media URLs and task IDs with your own usable inputs.

15-second 4K portrait video

Image-to-video and subject references

First/last-frame interpolation

Specifying frames with image roles

Video editing

Editing preserves the source video length; duration has no effect. Use short, specific editing instructions. For a local change, add Keep everything else the same.

Extending a previous task

To extend an uploaded video, replace extend_from_task_id with video_urls and keep "omni_reference_task_type": "extend". The returned video contains the original followed by the added segment. duration controls only the added length, up to 10 seconds, and only the added seconds are billed. For example, a 5-second source with duration: 4 returns a video of about 9 seconds.

Submission response and task status

A successful submission returns HTTP 200; read data[0].task_id. Poll the task status endpoint every 5–10 seconds until completed or failed. Allow 10 minutes overall. If your client times out, keep querying the original task instead of submitting it again.
Timing examples: a 15-second 360p video takes about 30 seconds; a 15-second 4K video takes about 5 minutes. These are estimates; use task status as the authority.
data in the query response is the task object. data.result.videos[0].url is an array; the first video URL is data.result.videos[0].url[0]. Download or play it directly, and archive it for long-term storage. data.cost is the final charge in USD.

Billing and reserved balance

Token-based billing: resolution affects video output tokens per second. For text-to-video and image-to-video, duration specifies the output length. Editing ignores it and preserves the source video length; extension uses it only for the added segment. See APIMart pricing for actual rates. At submission, balance is reserved using the resolution and max(10, duration) seconds; video input is estimated at 15 seconds. This reservation is not the final charge. After success, it is adjusted to actual usage; read data.cost for the final amount. Extension is charged only for added seconds. Failed tasks are not charged. Insufficient balance for the reservation returns HTTP 402.

Error handling

Parameter errors (invalid_* / unsupported_*) immediately set the task to failed without a charge. Check task status even after successful submission.

FAQ

Is prompt required when I provide images or video?

Yes. Every mode requires prompt, including image-to-video, first/last-frame interpolation, editing, extension, and video reuse through extend_from_task_id. Omitting this field returns HTTP 400.

Can I send Base64 images or video directly?

No. image_urls, first_frame_image, last_frame_image, image_with_roles[].url, and video_urls accept only publicly accessible HTTP(S) direct URLs. Do not send data:image/..., data:video/..., or raw Base64 strings.