MaaS_VEO

Request Protocol

Http

Request Header

Parameter Name	Value
Authorization	Bearer
Content-Type	multipart/form-data

Generate Video

Request URL

POST

https://genaiapi.cloudsway.net/v1/ai/{Your Endpoint}/veo/videos/generate

Request Body

Objects in instances

Attribute Name	Type	Required/Optional	Description
prompt	string	Parameters required for the text-to-video function. Optional if an input image prompt (converting an image to a video) is provided.	A text string used to guide the first eight seconds of the video. For example: Fast Track Shot: Depicts a bustling dystopian world illuminated by bright neon lights, flying cars, mist, night, halos, and volumetric lighting Neon holograms of cars traveling at full speed at the speed of light, cinematic visuals, incredible details, volumetric lighting Many spotted jellyfish pulsate underwater. Their bodies are transparent and glow in the deep sea Shallow depth of field puddles on the street captured at extremely close range, reflecting the futuristic Tokyo city, with bright neon lights, at night, with halos Time-lapse photography of the dancing aurora borealis, twinkling stars, and snow-covered landscape in the Arctic sky Under the beautiful afterglow of the setting sun, a solitary cowboy rides a horse galloping across the open plain, with soft light and warm colors
image	Media	Optional	Optional. The image used to guide video generation can be a `bytesBase64Encoded` string encoding the image or a `gcsUri` string URI of a Cloud Storage bucket location.
lastFrame	Media	Optional	Optional. The image of the first frame of the video, used to fill the space between them.`lastFrame` can be a `bytesBase64Encoded` string of the encoded image, or a `gcsUri` string URI of a Cloud Storage bucket location. `lastFrame` is supported by the following preview version models: `MaaS_Veo_3.1_generate_preview` `MaaS_Veo_3.1_fast_generate_preview`
referenceImages	Media	Optional	`list[referenceImages]` Optional. A list containing up to three creative resource images or up to one style image, used to describe the `referenceImages` to be used by the model when generating videos. Important Note: The Veo 3.1 model does not support `referenceImages.style`. The following models support referenceImages in the `preview version` : `MaaS_Veo_3.1_generate_preview`
referenceImages.image	Media	Optional	Optional. Each image can be a `bytesBase64Encoded` string encoding the image, or a `gcsUri` string URI of a Cloud Storage bucket location.
referenceImages.referenceType	string	is required in the referenceImages object	is required in the referenceImages object. Specifies the type of the provided reference image. The following values are supported: "asset": Reference images provide creative resources for the generated video, such as scenes, objects, or characters. "style": The reference image provides style information for the generated video, such as scene color, lighting, or texture. Important Note: The Veo 3.1 model does not support referenceImages.style, and veo-3.1-lite-generate-001 does not support referenceImages.style and referenceImages.asset

Media Object

Attribute Name	Type	Description
bytesBase64Encoded	string	Base64-encoded string of the ByteDance of the image or video file.
gcsUri	string	A string URI pointing to the location of a Cloud Storage bucket.
mimeType	string	The following objects must have this parameter: image video mask lastFrame referenceImages.image Specify the MIME type of the video or image. For images, the system accepts the following MIME types: image/jpeg image/png image/webp For videos, the system accepts the following MIME types: video/mov video/mpeg video/mp4 video/mpg video/avi video/wmv video/mpegps video/flv

Parameters object

Attribute Name	Type	Required/Optional	Description
aspectRatio	string	Optional	Specifies the aspect ratio of the generated video. Acceptable values are `16:9` (default) or `9:16`.
compressionQuality	string	Optional	Specifies the compression quality of the generated video. Acceptable values are "optimized" or "lossless". The default value is "optimized".
durationSeconds	integer	Required	Duration of the video file to be generated: Veo 2 Model: `5`-`8`. The default value is `8`. Veo 3 Model:`4`, `6`, or `8`. Default is `8`. When using `referenceImages`: `8`.
enhancePrompt	boolean	Optional	Use Gemini to optimize prompts. Acceptable values are `true` or `false` (default is `true`). The following models support enhancePrompt: • veo-2.0-generate-001 • veo-2.0-generate-preview • veo-2.0-generate-exp
generateAudio	boolean	Required (only for `MaaS_Veo_3_generate_preview`) See detailed description	Required parameter for MaaS_Veo_3_generate_preview. Generates audio for the video. Acceptable values are true or false. When calling the original factory interface, if the field is not filled in MaaS_Veo_3_generate_preview, audio will be generated by default.
negativePrompt	string	Optional	A text string used to describe the content you want to prevent the model from generating. For example: Top lighting, bright colors Characters, Animals Multiple cars, wind
personGeneration	string	Optional	Security settings to control whether to allow character or face generation: allow_adult (default): Only allow generating adults dont_allow: Prohibit including people/faces in the image
resizeMode	string	Optional	Only applicable to the Veo 3 model, when used in conjunction with image, it can achieve image-to-video conversion. The adjustment mode used by the model to resize the video. Accepted values include "pad" (default) or "crop".
resolution	string	Optional	Only applicable to the Veo 3 model. The resolution of the generated video, with acceptable values being `720p` (default), `1080p`, 4k (only for the Veo 3.1 Preview model).
sampleCount	int	Optional	The number of output videos requested. Accepted values are 1-4.
seed	uint32	Optional	The requested number, used to generate a deterministic video (seed value). The range is `0-4294967295`.
storageUri	string	Optional	The Cloud Storage bucket URI for storing the output video, formatted as `gs://BUCKET_NAME/SUBDIRECTORY`. If not provided, returns the Base64-encoded video bytes.

Request Example

Image-to-Video

curl 'https://genaiapi.cloudsway.net/v1/ai/{Your Endpoint}/veo/videos/generate' \
-H 'Authorization: Bearer {Your AK}' \
-H 'Content-Type: application/json' \
-d '{
    "instances": [
        {
            "prompt": "",
            "image": {
                "bytesBase64Encoded": "INPUT_IMAGE",
                "mimeType": "MIME_TYPE"
             }
        }
    ],
    "parameters": {
        "durationSeconds": 8,
        "generateAudio": true
    }
}'

Text-to-Video

curl 'https://genaiapi.cloudsway.net/v1/ai/{Your Endpoint}/veo/videos/generate' \
-H 'Authorization: Bearer {Your AK}' \
-H 'Content-Type: application/json' \
-d '{
    "instances": [
        {
            "prompt": ""
        }
    ],
    "parameters": {
        "durationSeconds": 8,
        "generateAudio": true
    }
}'

Video using creative resource images

curl 'https://genaiapi.cloudsway.net/v1/ai/{Your Endpoint}/veo/videos/generate' \
-H 'Authorization: Bearer {Your AK}' \
-H 'Content-Type: application/json' \
-d '{
    "instances": [
        {
            "prompt": "",
            "referenceImages": [
                {
                    "image": {
                        "bytesBase64Encoded": "",
                        "mimeType": "image/png"
                    },
                    "referenceType": "asset"
                }
            ]
        }
    ],
    "parameters": {
        "durationSeconds": 8,
        "generateAudio": false
    }
}'

Return Value Example

Complete parameters of the return value

{
        "instances": [{
               "prompt": string,
               "image": {
                    // Union field can be only one of the following:
                    "bytesBase64Encoded": string,
                    "gcsUri": string,
                    // End of list of possible types for union field.
                    "mimeType": string
               },
              "lastFrame": {
                    // Union field can be only one of the following:
                    "bytesBase64Encoded": string,
                    "gcsUri": string,
                    // End of list of possible types for union field.
                    "mimeType": string
              },
              "video": {
                    // Union field can be only one of the following:
                    "bytesBase64Encoded": string,
                    "gcsUri": string,
                    // End of list of possible types for union field.
                    "mimeType": string
              },
              "referenceImages": [
                // A list of up to three asset images or at most one style image for the
                // model to use when generating videos.
                //
                // referenceImages is supported by the following models in Preview:
                //
                // *   veo-2.0-generate-exp
                // *   veo-3.1-generate-preview
                {
                    "image:" {
                      // Union field can be only one of the following:
                      "bytesBase64Encoded": string,
                      "gcsUri": string,
                      // End of list of possible types for union field.
                      "mimeType": string
                    },
                    "referenceType": string
                }
              ]
        }],
        "parameters": {
                "aspectRatio": string,
                "compressionQuality": string,
                "durationSeconds": integer,
                "enhancePrompt": boolean,
                "generateAudio": boolean,
                "negativePrompt": string,
                "personGeneration": string,
                "resizeMode": string, // Veo 3 image-to-video only
                "resolution": string, // Veo 3 models only
                "sampleCount": integer,
                "seed": uint32,
                "storageUri": string
        }
}

{  "name": "OPERATION_ID"}

Query Task

Request URL

https://genaiapi.cloudsway.net/v1/ai/{Your Endpoint}/veo/videos/task

Input Parameter Example

{
  "operationName": "OPERATION_ID"
}

Return Value Example

Task completed, video generation successful

{
   "name": string,
   "done": boolean,
   "response":{
      "@type":"type.googleapis.com/cloud.ai.large_models.vision.GenerateVideoResponse",
      "raiMediaFilteredCount": integer,
      "videos":[
         {
           // Union field can be only one of the following:
           "gcsUri": string,
           "bytesBase64Encoded": string,
           // End of list of possible types for union field.
           "mimeType": string
         },
         {
           // Union field can be only one of the following:
           "gcsUri": string,
           "bytesBase64Encoded": string,
           // End of list of possible types for union field.
           "mimeType": string
         },
         {
           // Union field can be only one of the following:
           "gcsUri": string,
           "bytesBase64Encoded": string,
           // End of list of possible types for union field.
           "mimeType": string
         },
         {
           // Union field can be only one of the following:
           "gcsUri": string,
           "bytesBase64Encoded": string,
           // End of list of possible types for union field.
           "mimeType": string
         },
      ]
   }
}

Task completed, error generating video

{
    "name": string,
    "done": boolean,
    "error": {
        "code": integer,
        "message": string
    }
}

Error Code

Task Creation Phase

{
    "error": {
        "code": "400",
        "message": "{\n  \"error\": {\n    \"code\": 400,\n    \"message\": \"Invalid compression quality type: notvalid\",\n    \"status\": \"INVALID_ARGUMENT\"\n  }\n}\n"
    }
}

HTTP Status Code	error.code	error.message
200	0
400	400	Status: INVALID_ARGUMENT message: Invalid resize mode Invalid compression quality type No inputs provided Invalid referenceType image is empty Invalid resolution
401	401	You are not authorized to access this resource.
500		Internal Server Error
429	429	The request frequency exceeds the upper limit set by the Client. Please contact customer service staff for adjustment.

Query Task Phase

The "done" field indicates whether the task has been completed, regardless of success or failure. "true" indicates completion, and error information needs to be determined through the "error" field and the information in the "response" field.

{
    "data": {
        "name": "xxxxxxx",
        "done": true,
        "error": {
            "code": 3,
            "message": "Reference to video does not support this mix of reference images."
        }
    }
}

HTTP Status Code	error.code	error.message
200	0
200	3	Unsupported output video duration 4 seconds, supported durations are [8] for feature reference_to_video. Unsupported output video duration 34 seconds, supported durations are [8,4,6] for feature text_to_video. Unsupported output video duration 14 seconds, supported durations are [8,4,6] for feature image_to_video. Generated video is large, an output storage uri is required. Reference to video does not support this mix of reference images. Unsupported output storage uri Invalid sample count 6. The sample count should be in the range of [1, 4].
200	7	service-341959507421@gcp-sa-aiplatform.iam.gserviceaccount.com does not have storage.objects.create access to the Google Cloud Storage object. Permission 'storage.objects.create' denied on resource (or it may not exist). service-341959507421@gcp-sa-aiplatform.iam.gserviceaccount.com does not have storage.objects.create access to the Google Cloud Storage object. Permission 'storage.objects.create' denied on resource (or it may not exist).
401	401	You are not authorized to access this resource.
500		Internal Server Error
429	429	The request frequency exceeds the upper limit set by the Client. Please contact customer service staff for adjustment.

When a task is successfully created and queried, it may fail due to some sensitive information. An example of the returned result is as follows, where the codes at the end of raiMediaFilteredReasons may not necessarily correspond to specific filtering reasons, as some model sides do not provide specific filtering reasons.

{
  "name": "9a0be521-bf8b-449f-9c2d-f22f9d5088c5",
  "done": true,
  "response": {
    "raiMediaFilteredCount": 1,
    "raiMediaFilteredReasons": [
      "Your current safety settings for people/face generation filtered out 1 videos. You will not be charged for blocked videos. Try rephrasing the prompt. If you think this was an error, send feedback. Support codes: 39322892, 63236870"
    ]
  }
}

The relationship between the code and the specific reason is as follows

Support Code	Security Category	Description
58061214 17301594	Children	If personGeneration is not set to "allow_all", or the project is not on the permission list for this feature, requests to generate content depicting children will be rejected.
29310472 15236754	Celebrity	Reject requests to generate realistic representations of well-known individuals, or requests for projects not on the approved list for this feature.
64151117 42237218	Video security violation	Detect content that violates security policies.
62263041	Dangerous content	Detect content that is potentially dangerous in nature.
57734940 22137204	annoying	Detect themes or content related to hatred.
74803281 29578790 42876398	Other	Detect various other security issues in the request
92201652	Personal Information	Detect personally identifiable information (PII) in text, such as references to credit card numbers, addresses, or other such information.
89371032 49114662 72817394	Prohibited Content	Detect prohibited content in the request.
90789179 63429089 43188360	Pornographic content	Detect pornographic content.
78610348	Harmful Content	Detect harmful themes or content in the text.
61493863 56562880	Violence	Detect violence-related content in videos or text.
32635315	vulgar	Detect vulgar themes or content in the text.