Gemini Video generation - ZnapAI Documentation

3-Step Video Generation Workflow

Step 1: Initiate Video Generation

Request a new video generation task by calling the :predictLongRunning RPC on the model.

curl --location 'https://api.znapai.com/gemini/v1beta/models/veo-3.1-generate-preview:predictLongRunning' \
--header 'x-goog-api-key: $ZnapAI_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "instances": [
      {
        "prompt": "A cat playing with a ball of yarn in a sunny garden"
      }
    ],
    "parameters": {
      "durationSeconds": 4,
      "resolution": "720p",
      "aspectRatio": "16:9"
    }
  }'

Response

{
  "name": "models/veo-3.1-generate-preview/operations/{OPERATION_ID}"
}

Step 2: Poll for Completion

Using the operation ID returned from Step 1, poll the status endpoint until "done": true is returned.

curl --location 'https://api.znapai.com/gemini/v1beta/models/veo-3.1-generate-preview/operations/{OPERATION_ID}' \
--header 'x-goog-api-key: $ZnapAI_API_KEY'

Response (Once Completed)

{
  "name": "models/veo-3.1-generate-preview/operations/{OPERATION_ID}",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.ai.generativelanguage.v1beta.PredictLongRunningResponse",
    "generateVideoResponse": {
      "generatedSamples": [
        {
          "video": {
            "uri": "https://generativelanguage.googleapis.com/v1beta/files/{FILE_ID}:download?alt=media"
          }
        }
      ]
    }
  }
}

Step 3: Download Video

Substitute the Google API host (https://generativelanguage.googleapis.com/v1beta) with the proxy base URL (https://api.znapai.com/gemini/v1beta) to route the download request through ZnapAI.

curl --location 'https://api.znapai.com/gemini/v1beta/files/{FILE_ID}:download?alt=media' \
--header 'x-goog-api-key: $ZnapAI_API_KEY' \
--output generated_video.mp4

Supported Generation Modes

Feature	Parameter(s)	Status
Text → Video	`prompt`	✅ Supported
Image → Video	`image`	✅ Supported
First Frame & Last Frame	`firstFrame`, `lastFrame`	✅ Supported (only works with duration of 8 sec)
Video Extension	`video`	✅ Supported (not on lite; input must be a Veo-generated video)
Reference Images	`referenceImages`	✅ Supported (not on lite; requires 8 sec duration)
Video Duration	`durationSeconds`	✅ Supported
Aspect Ratio	`aspectRatio`	✅ Supported
Seed	`seed`	✅ Supported
Negative Prompt	`negativePrompt`	⚠️ Partial

Model Feature Support

As tested through this proxy, veo-3.1-generate-preview and veo-3.1-fast-generate-preview behave identically for every feature below; veo-3.1-lite-generate-preview differs on reference images and negative prompt.

Feature	`veo-3.1-generate-preview` & `veo-3.1-fast-generate-preview`	`veo-3.1-lite-generate-preview`
Text → Video	✅ Supported	✅ Supported
Image → Video	✅ Supported	✅ Supported
First & Last Frame	✅ Supported (`durationSeconds: 8` required)	✅ Supported (`durationSeconds: 8` required)
Reference Images	✅ Supported (`durationSeconds: 8` or omitted required)	❌ Not supported (any duration)
Video Extension	✅ Supported (input must be a Veo-generated video)	❌ Not supported
Negative Prompt	✅ Supported	❌ Not supported

First & Last Frame Generation (Interpolation)

You can generate a video transition between two images (a starting state and an ending state) by providing both a first frame and a last frame:

First Frame: Can be passed via instances[0].firstFrame or instances[0].image.
Last Frame: Must be passed via instances[0].lastFrame.

The model will generate a smooth animation interpolating between the two frames based on the prompt.

Unlike referenceImages, first/last frame interpolation is supported across all three model variants: veo-3.1-generate-preview, veo-3.1-lite-generate-preview, and veo-3.1-fast-generate-preview.

Example Request:

curl --location 'https://api.znapai.com/gemini/v1beta/models/veo-3.1-generate-preview:predictLongRunning' \
--header 'x-goog-api-key: $ZnapAI_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "instances": [
      {
        "prompt": "Smooth cinematic transition from a sunny orange-purple gradient scene with a yellow sun to a cool blue-green gradient scene with a red square target",
        "image": {
          "bytesBase64Encoded": "<BASE64_FIRST_FRAME_PNG>",
          "mimeType": "image/png"
        },
        "lastFrame": {
          "bytesBase64Encoded": "<BASE64_LAST_FRAME_PNG>",
          "mimeType": "image/png"
        }
      }
    ],
    "parameters": {
      "aspectRatio": "16:9",
      "durationSeconds": 8,
      "resolution": "720p"
    }
  }'

Reference Images (Subject Consistency)

You can guide the appearance of a subject (e.g. a character or object) across the generated video by providing 1–3 reference images via instances[0].referenceImages, each with a referenceType of "asset".

referenceImages is not supported on veo-3.1-lite-generate-preview, regardless of duration — it always returns a model-specific 400 error. It works on both veo-3.1-generate-preview and veo-3.1-fast-generate-preview once durationSeconds is set to 8 (or omitted).

Example Request:

curl --location 'https://api.znapai.com/gemini/v1beta/models/veo-3.1-generate-preview:predictLongRunning' \
--header 'x-goog-api-key: $ZnapAI_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "instances": [
      {
        "prompt": "The blue robot character from the reference image walks across a futuristic neon city street at night, looking around curiously",
        "referenceImages": [
          {
            "image": {
              "bytesBase64Encoded": "<BASE64_REFERENCE_IMAGE_PNG>",
              "mimeType": "image/png"
            },
            "referenceType": "asset"
          }
        ]
      }
    ],
    "parameters": {
      "aspectRatio": "16:9",
      "durationSeconds": 8,
      "resolution": "720p"
    }
  }'

Video Extension

You can extend a previously generated Veo video by 7 seconds (repeatable up to 20 times) by passing it via instances[0].video.

Pass the video as "video": {"uri": "<file-download-url>"} — the URI returned from a prior predictLongRunning poll response (response.generateVideoResponse.generatedSamples[0].video.uri). Passing raw video bytes via bytesBase64Encoded (or inlineData) fails with "Video URI not found in the request." Video extension is not supported on veo-3.1-lite-generate-preview; it works on both veo-3.1-generate-preview and veo-3.1-fast-generate-preview.

Example Request:

curl --location 'https://api.znapai.com/gemini/v1beta/models/veo-3.1-generate-preview:predictLongRunning' \
--header 'x-goog-api-key: $ZnapAI_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "instances": [
      {
        "prompt": "The camera continues panning across the cool blue-green gradient scene, the red square target pulses gently with light",
        "video": {
          "uri": "https://generativelanguage.googleapis.com/v1beta/files/<FILE_ID>:download?alt=media"
        }
      }
    ],
    "parameters": {
      "resolution": "720p"
    }
  }'

Chaining Extensions (Extend Again)

To extend a video more than once, take the uri from the most recent extension’s completed poll response — not the original input video — and pass that into the next extension request. The call shape is identical each time; only the uri and prompt change.

Confirmed working: extending an already-extended video succeeds the same way as the first extension, with no different payload shape or extra fields required. Each successful call adds another ~7 seconds and returns a new uri to chain from for the next call, up to 20 times total.

Example Request (extending an already-extended video):

curl --location 'https://api.znapai.com/gemini/v1beta/models/veo-3.1-generate-preview:predictLongRunning' \
--header 'x-goog-api-key: $ZnapAI_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "instances": [
      {
        "prompt": "The scene shifts further, the red square target now floats gently upward into a starry night sky",
        "video": {
          "uri": "https://generativelanguage.googleapis.com/v1beta/files/<FILE_ID_FROM_PREVIOUS_EXTENSION>:download?alt=media"
        }
      }
    ],
    "parameters": {
      "resolution": "720p"
    }
  }'

Parameter Specifications

Optional Parameters

string

A text description of the video you want to generate.

object

Input image for Image-to-Video generation. Can also be used as the starting (first) frame when paired with lastFrame.

object

Input image to guide the ending (last) frame of the video, enabling smooth transition/interpolation between the first and last frames.

object

A previously Veo-generated video to extend by 7 seconds. Must be passed as {"uri": "<file-download-url>"}, not as raw bytes.

Not supported on veo-3.1-lite-generate-preview. Supported on veo-3.1-generate-preview and veo-3.1-fast-generate-preview. See Video Extension Validation below.

array

A list of 1–3 images used to guide the appearance of a subject (e.g. a character or object) across the generated video. Each entry needs a referenceType of "asset".

Not supported on veo-3.1-lite-generate-preview (always rejected). Supported on veo-3.1-generate-preview and veo-3.1-fast-generate-preview, but only when durationSeconds is 8 (or omitted) — any other duration is rejected. See Reference Images Model Support below.

integer

The length of the generated video in seconds. Supported values: 4, 6, or 8.

If using first-to-last frame interpolation, the duration must be set to exactly 8 seconds; shorter durations are not supported.

string

The aspect ratio of the output video. Supported values: "16:9", "9:16".

string

The resolution of the output video. E.g., "720p".

integer

A seed value to guide the randomness of generation.

string

Description of elements you want to avoid in the video.

This parameter is not supported by veo-3.1-lite-generate-preview. Passing it will trigger a 400 Bad Request validation error.

Validation & Error Behaviour

Negative Prompt Validation on Lite Model

Passing a negativePrompt parameter to the veo-3.1-lite-generate-preview model will result in a 400 Bad Request error:

{
  "error": {
    "message": "{\n  \"error\": {\n    \"code\": 400,\n    \"message\": \"`negativePrompt` isn't supported by this model. Please remove it or refer to the Gemini API documentation for supported usage.\",\n    \"status\": \"INVALID_ARGUMENT\"\n  }\n}\n",
    "type": "None",
    "param": "None",
    "code": "400"
  }
}

Reference Images Limit

Providing more than 3 reference images will result in a validation error:

{
  "error": {
    "message": "{\n  \"error\": {\n    \"code\": 400,\n    \"message\": \"Number of reference images can not exceed 3.\",\n    \"status\": \"INVALID_ARGUMENT\"\n  }\n}\n",
    "type": "None",
    "param": "None",
    "code": "400"
  }
}

Observed Behaviour: 1–3 reference images are accepted; 4 or more reference images are rejected.

Reference Images Model Support

referenceImages (schema: image.bytesBase64Encoded + referenceType: "asset") was tested against all three model variants. The key finding: it works on the full and fast models, but only with durationSeconds: 8 — passing 4 (or 6) triggers a generic error that looks like a model-support issue but is actually a duration mismatch.

Model	With `durationSeconds: 8` (or omitted)	With `durationSeconds: 4`
`veo-3.1-generate-preview`	✅ Succeeds	❌ Rejected (generic error)
`veo-3.1-fast-generate-preview`	✅ Succeeds	❌ Rejected (generic error)
`veo-3.1-lite-generate-preview`	❌ Rejected (model-specific error)	❌ Rejected (model-specific error)

veo-3.1-lite-generate-preview always rejects with a model-specific message, regardless of duration:

{
  "error": {
    "message": "{\n  \"error\": {\n    \"code\": 400,\n    \"message\": \"`referenceImages` isn't supported by this model. Please remove it or refer to the Gemini API documentation for supported usage.\",\n    \"status\": \"INVALID_ARGUMENT\"\n  }\n}\n",
    "type": "None",
    "param": "None",
    "code": "400"
  }
}

veo-3.1-generate-preview and veo-3.1-fast-generate-preview reject with this generic message only when durationSeconds isn’t 8:

{
  "error": {
    "message": "{\n  \"error\": {\n    \"code\": 400,\n    \"message\": \"Your use case is currently not supported.  Please refer to Gemini API documentation for current model offering.\",\n    \"status\": \"INVALID_ARGUMENT\"\n  }\n}\n",
    "type": "None",
    "param": "None",
    "code": "400"
  }
}

Observed Behaviour: With durationSeconds: 8 set (or parameters omitted entirely), both the full and fast models return 200 and complete generation successfully. The lite model rejects unconditionally, confirming it’s a genuine capability gap rather than a duration issue.

`inlineData` Image Encoding Rejected

Google’s SDKs/REST examples wrap image bytes as image: { inlineData: { mimeType, data } }. This proxy does not accept that shape for any image field — use bytesBase64Encoded instead:

{
  "error": {
    "message": "{\n  \"error\": {\n    \"code\": 400,\n    \"message\": \"`inlineData` isn't supported by this model. Please remove it or refer to the Gemini API documentation for supported usage.\",\n    \"status\": \"INVALID_ARGUMENT\"\n  }\n}\n",
    "type": "None",
    "param": "None",
    "code": "400"
  }
}

Video Extension Validation

instances[0].video must reference a previously Veo-generated video by its file download URI — passing raw video bytes fails:

{
  "error": {
    "message": "{\n  \"error\": {\n    \"code\": 400,\n    \"message\": \"Video URI not found in the request.\",\n    \"status\": \"INVALID_ARGUMENT\"\n  }\n}\n",
    "type": "None",
    "param": "None",
    "code": "400"
  }
}

veo-3.1-lite-generate-preview rejects video extension outright:

{
  "error": {
    "message": "{\n  \"error\": {\n    \"code\": 400,\n    \"message\": \"Video extension is not allowed for this model.\",\n    \"status\": \"INVALID_ARGUMENT\"\n  }\n}\n",
    "type": "None",
    "param": "None",
    "code": "400"
  }
}

Observed Behaviour: {"video": {"uri": "<file-download-url>"}} succeeds and completes on both veo-3.1-generate-preview and veo-3.1-fast-generate-preview. veo-3.1-lite-generate-preview rejects the request regardless of payload shape. Chaining a second extension off an already-extended video’s uri was also tested and completes successfully, with an identical request shape to the first extension.

Validation Scenarios

Scenario	Result / Error
More than 3 reference images	Rejected with correct validation error
`referenceImages` on lite model	Rejected — unsupported on this model, any duration
`referenceImages` on full/fast model with `durationSeconds: 8`	✅ Succeeds
`referenceImages` on full/fast model with `durationSeconds: 4`	Rejected — generic “use case not supported” error
`image` using `inlineData` encoding	Rejected — proxy requires `bytesBase64Encoded`
`lastFrame` without `image`	Unsupported request
`lastFrame` with `durationSeconds` under 8	Unsupported request (requires exactly 8 seconds)
`video` with raw bytes (not a `uri`)	Rejected — `"Video URI not found in the request."`
Video extension on lite model	Rejected — `"Video extension is not allowed for this model."`
`fileData` parameter	Explicitly rejected

Unsupported Fields

fileData

Passing fileData (such as fileUri or mimeType inside the video object) is explicitly unsupported:

{
  "video": {
    "fileData": {
      "mimeType": "video/mp4",
      "fileUri": "..."
    }
  }
}

Response:

`fileData` isn't supported by this model.

​3-Step Video Generation Workflow

​Step 1: Initiate Video Generation

​Response

​Step 2: Poll for Completion

​Response (Once Completed)

​Step 3: Download Video

​Supported Generation Modes

​Model Feature Support

​First & Last Frame Generation (Interpolation)

​Reference Images (Subject Consistency)

​Video Extension

​Chaining Extensions (Extend Again)

​Parameter Specifications

​Optional Parameters

​Validation & Error Behaviour

​Negative Prompt Validation on Lite Model

​Reference Images Limit

​Reference Images Model Support

​inlineData Image Encoding Rejected

​Video Extension Validation

​Validation Scenarios

​Unsupported Fields

​fileData

3-Step Video Generation Workflow

Step 1: Initiate Video Generation

Response

Step 2: Poll for Completion

Response (Once Completed)

Step 3: Download Video

Supported Generation Modes

Model Feature Support

First & Last Frame Generation (Interpolation)

Reference Images (Subject Consistency)

Video Extension

Chaining Extensions (Extend Again)

Parameter Specifications

Optional Parameters

Validation & Error Behaviour

Negative Prompt Validation on Lite Model

Reference Images Limit

Reference Images Model Support

`inlineData` Image Encoding Rejected

Video Extension Validation

Validation Scenarios

Unsupported Fields

fileData