MaaS_VEO视频接口文档

请求协议

Http

参数名	值
Authorization	Bearer {YOUR AK}
Content-Type	multipart/form-data

生成视频

请求URL

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

请求Body

instances中对象

属性名	类型	必需/可选	描述
prompt	string	文本转视频功能必需的参数。如果提供了输入图片提示（将图片转换为视频），则为可选。	一个文本字符串，用于引导视频的前八秒。例如：快速轨道镜头：在光线明亮的霓虹灯、飞行的汽车和迷雾、夜晚、光晕、体积光照的照明下，描绘了一个繁华的反乌托邦世界汽车以光速全速行驶的霓虹全息图，电影般的画面，令人难以置信的细节，体积光照许多斑点水母在水下脉动。它们的身体是透明的，在深海中会发光极近距离拍摄的街道上浅景深的积水。反射出未来主义的东京城市，霓虹灯明亮，夜晚，有光晕北极天空中舞动的北极光、闪烁的星星、白雪覆盖的景观的延时摄影在美丽的落日余晖下，一个孤独的牛仔骑着马在开阔的平原上奔驰，光线柔和，色彩温暖
image	Media	可选	可选。用于指导视频生成的图片，可以是编码图片的 `bytesBase64Encoded` 字符串，也可以是 Cloud Storage 存储桶位置的 `gcsUri` 字符串 URI。
lastFrame	Media	可选	可选。视频第一帧的图片，用于填充两者之间的空间。`lastFrame` 可以是编码图片的 `bytesBase64Encoded` 字符串，也可以是 Cloud Storage 存储桶位置的 `gcsUri` 字符串 URI。`lastFrame` 支持的模型： `MaaS_Veo_3.1_generate_preview` `MaaS_Veo_3.1_fast_generate_preview`
referenceImages	Media	可选	`list[referenceImages]`可选。最多包含三张素材资源图片或最多一张风格图片的列表，用于描述模型在生成视频时要使用的 `referenceImages`。重要提示：Veo 3.1 模型不支持 `referenceImages.style`。以下模型在预览版中支持 `referenceImages`： `MaaS_Veo_3.1_generate_preview`
referenceImages.image	Media	可选	可选。每张图片可以是为图片编码的。 `bytesBase64Encoded`字符串，也可以是 Cloud Storage 存储桶位置的 `gcsUri` 字符串 URI。
referenceImages.referenceType	string	在 referenceImages 对象中是必需的	在 referenceImages 对象中是必需的。指定所提供的参考图片的类型。支持以下值："asset"：参考图片为生成的视频提供素材资源，例如场景、对象或角色。"style"：参考图片为生成的视频提供风格信息，例如场景颜色、光照或纹理。重要提示：Veo 3.1 模型不支持 referenceImages.style。

Media对象

属性名	类型	描述
bytesBase64Encoded	string	图片或视频文件的字节 Base64 编码字符串。
gcsUri	string	指向 Cloud Storage 存储桶位置的字符串 URI。
mimeType	string	以下对象必须具有此参数：imagevideomasklastFramereferenceImages.image指定视频或图片的 MIME 类型。对于图片，系统接受以下 MIME 类型：image jpegimage pngimage webp对于视频，系统接受以下 MIME 类型：video movvideo mpegvideo mp4video mpgvideo avivideo wmvvideo mpegpsvideo flv

parameters对象

属性名	类型	必需/可选	描述
aspectRatio	string	可选	指定所生成视频的宽高比。可接受值为 `16:9`（默认值）或 `9:16`。
compressionQuality	string	可选	指定所生成视频的压缩质量。可接受的值为 "optimized" 或 "lossless"。默认值为 "optimized"。
durationSeconds	integer	必需	要生成的视频文件的时长： Veo 2 模型： `5`-`8`。默认值为 `8`。 Veo 3 模型：`4`、`6` 或 `8`。默认为 `8`。使用 `referenceImages` 时：`8`。
enhancePrompt	boolean	可选	使用 Gemini 优化提示。可接受值为 `true` 或 `false`（默认值为 `true`）。
generateAudio	boolean	必需（仅限 `MaaS_Veo_3_generate_preview`）详见描述	MaaS_Veo_3_generate_preview 的必需参数。为视频生成音频。可接受的值为 true 或 false。调原厂接口，MaaS_Veo_3_generate_preview不填这个字段默认会生成音频。
negativePrompt	string	可选	一个文本字符串，用于描述您想要阻止模型生成的内容。例如：顶部照明、明亮的色彩人物、动物多辆汽车、风
personGeneration	string	可选	控制是否允许人物或人脸生成的安全设置： allow_adult（默认值）：仅允许生成成年人 dont_allow：禁止在图片中包含人物/人脸
resizeMode	string	可选	仅限 Veo 3 模型，与 image 搭配使用，可实现图像转视频。模型用于调整视频大小的调整模式。接受的值包括 "pad"（默认值）或 "crop"。
resolution	string	可选	仅限 Veo 3 模型。生成视频的分辨率，可接受值为 `720p`（默认值）或 `1080p`。
sampleCount	int	可选	请求的输出视频数量。接受的值为 1-4。
seed	uint32	可选	请求的数字，用于生成确定性视频（种子值）。范围为 `0-4,294,967,295`。
storageUri	string	可选	用于存储输出视频的 Cloud Storage 存储桶 URI，格式为 `gs://BUCKET_NAME/SUBDIRECTORY`。如果未提供，则返回以 Base64 编码的视频字节。

请求示例

文生视频

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
    }
}'

图生视频

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
    }
}'

使用素材资源图片的视频

curl 'https://genaiapipre.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
    }
}'

返回值示例

返回值完整参数

{
        "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": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/OPERATION_ID"}

查询任务

请求URL

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

入参示例

{
  "operationName": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/OPERATION_ID"
}

返回值示例

任务完成，生成视频成功

{
   "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
         },
      ]
   }
}

任务完成，生成视频错误

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

错误码

创建任务阶段

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

HTTP 状态码	error.code	error.message
200	0
400	400	Status: INVALID_ARGUMENTmessage: 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	请求频次超过客户端设置上限，请联系客服人员进行调整

查询任务阶段

done字段表示任务是否完成，无论是否成功，true表示已完成，报错信息需要通过error字段以及response字段中的信息判断

{
    "data": {
        "name": "projects/my-project-xx-xxxxx/locations/us-central1/publishers/google/models/veo-3.1-generate-preview/operations/xxxxxxx",
        "done": true,
        "error": {
            "code": 3,
            "message": "Reference to video does not support this mix of reference images."
        }
    }
}

HTTP状态码	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].
401	401	You are not authorized to access this resource.
500		Internal Server Error
429	429	请求频次超过客户端设置上限，请联系客服人员进行调整

当任务创建成功，查询任务时，可能会因为一些敏感信息导致失败,返回示例如下，其中raiMediaFilteredReasons里最后的codes不一定能对应到具体的过滤原因，有些模型侧没给出具体的过滤原因

{
  "name": "projects/xxxx-veo/locations/us-central1/publishers/google/models/veo-3.0-generate-preview/operations/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"
    ]
  }
}

code和具体原因关系如下

支持代码	安全类别	说明
58061214 17301594	子女	如果 personGeneration 未设置为 "allow_all"，或者项目不在此功能的许可名单中，则拒绝生成描绘儿童的内容的请求。
29310472 15236754	名人	拒绝生成知名人士的逼真表示的请求，或者拒绝项目不在此功能的许可名单中的请求。
64151117 42237218	视频安全违规	检测违反安全政策的内容。
62263041	危险内容	检测本质上具有潜在危险的内容。
57734940 22137204	讨厌的	检测与仇恨相关的主题或内容。
74803281 29578790 42876398	其他	检测请求中的其他各种安全问题
92201652	个人信息	检测文本中的个人身份信息 (PII)，例如提及信用卡号、住址或其他此类信息。
89371032 49114662 72817394	禁止的内容	检测请求中的禁止的内容。
90789179 63429089 43188360	色情内容	检测色情性内容。
78610348	有害内容	检测文本中的有害主题或内容。
61493863 56562880	暴力	检测视频或文本中与暴力相关的内容。
32635315	粗俗	检测文本中的粗俗主题或内容。

MaaS_VEO视频接口文档

请求协议

请求Header

生成视频

请求URL

请求Body

instances中对象

Media对象

parameters对象

请求示例

文生视频

图生视频

使用素材资源图片的视频

返回值示例

查询任务

请求URL

入参示例

返回值示例

任务完成，生成视频成功

任务完成，生成视频错误

错误码

创建任务阶段

查询任务阶段