视频生成 | MaiToken

Veo 系列模型走 Gemini Veo 官方协议，平台透明转发。请求体使用 instances 和 parameters，提交后返回 operation，轮询至 done=true 后获取结果。可用模型名以列出模型返回为准，如 veo-3.1-generate-preview、veo-3.1-fast-generate-preview。

Authorizations

Authorizationstring必填

Bearer Token 认证，无需 Google API Key 或 GCP 凭证。获取 API Key：访问 API Key 管理页面

Authorization: Bearer YOUR_API_KEY

提交生成任务

POST /v1beta/models/{model}:predictLongRunning

Path 参数：

model（必填）：Veo 模型名称，以列出模型接口返回结果为准

请求体为 Gemini Veo 官方格式：

instances（object[]，必填）：生成输入
- prompt（string，必填）：视频内容、动作、镜头、风格及声音描述
- image（object，可选）：图生视频的首帧图片，按模型支持
  - bytesBase64Encoded（string，必填）：图片 Base64 内容，不包含 Data URL 前缀
  - mimeType（string，必填）：图片 MIME 类型，如 image/png、image/jpeg
parameters（object，可选）：生成参数
- sampleCount（integer，可选）：生成视频数量
- durationSeconds（integer，可选）：视频时长，单位为秒
- aspectRatio（string，可选）：画面比例，如 16:9、9:16
- resolution（string，可选）：输出分辨率，如 720p、1080p
- negativePrompt（string，可选）：不希望出现在视频中的内容
- personGeneration（string，可选）：人物生成策略
- seed（integer，可选）：随机种子
- enhancePrompt（boolean，可选）：是否增强提示词
- generateAudio（boolean，可选）：是否生成音频，仅支持具有音频能力的模型

不同 Veo 模型支持的参数和取值范围不同，平台按官方协议透传，不支持的字段或取值会由模型返回错误。

文生视频请求示例

curl --request POST \  --url https://api.maitoken.com/v1beta/models/veo-3.1-generate-preview:predictLongRunning \  --header 'Authorization: Bearer <token>' \  --header 'Content-Type: application/json' \  --data '{    "instances": [      {        "prompt": "电影感航拍，日落时海浪拍打礁石，镜头缓慢向前推进"      }    ],    "parameters": {      "sampleCount": 1,      "durationSeconds": 8,      "aspectRatio": "16:9",      "resolution": "720p",      "generateAudio": true    }  }'

图生视频请求示例

curl --request POST \  --url https://api.maitoken.com/v1beta/models/veo-3.1-generate-preview:predictLongRunning \  --header 'Authorization: Bearer <token>' \  --header 'Content-Type: application/json' \  --data '{    "instances": [      {        "prompt": "保持主体一致，镜头缓慢推进，背景云层自然流动",        "image": {          "bytesBase64Encoded": "IMAGE_BASE64",          "mimeType": "image/png"        }      }    ],    "parameters": {      "sampleCount": 1,      "durationSeconds": 8,      "aspectRatio": "16:9",      "resolution": "720p"    }  }'

查询任务状态

GET /v1beta/{operation_name}

operation_name 必须使用提交响应中的完整 name，不要自行替换模型名称或只截取任务 ID。

处理中响应

done 为 false 或尚未返回 done=true 时，任务仍在处理中：

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

成功响应

任务完成后 done=true，生成结果位于 response.generateVideoResponse.generatedSamples[]：

{  "name": "models/veo-3.1-generate-preview/operations/OPERATION_ID",  "done": true,  "response": {    "generateVideoResponse": {      "generatedSamples": [        {          "video": {            "uri": "https://api.maitoken.com/v1beta/files/FILE_ID:download?alt=media",            "encoding": "video/mp4"          }        }      ]    }  }}

根据渠道配置，video 会返回以下一种结果：

uri：视频下载地址
encodedVideo：Base64 编码的视频内容
encoding：视频 MIME 类型，如 video/mp4

失败响应

任务失败时 done=true，错误信息位于顶层 error：

{  "name": "models/veo-3.1-generate-preview/operations/OPERATION_ID",  "done": true,  "error": {    "code": 3,    "message": "Invalid request parameters"  }}

下载视频

结果包含 video.uri 时，使用返回的完整地址下载，并携带提交任务时使用的 API Key：

curl --location \  --url 'VIDEO_URI' \  --header 'Authorization: Bearer <token>' \  --output veo.mp4

结果包含 video.encodedVideo 时，将其作为标准 Base64 内容解码并保存为视频文件。

注意事项

任务查询和文件下载必须使用提交任务时所用的同一个 API Key
建议每 5～10 秒轮询一次，直到返回 done=true
遇到 429 或 5xx 时应使用指数退避，避免高频轮询
提交请求超时不代表任务创建失败；无法确认提交结果时直接重试可能生成重复任务并产生重复费用
已获得 operation name 后应始终查询原任务，不要为了等待结果重复提交
客户端等待超时不代表服务端任务失败，之后仍可使用原 operation 查询
视频地址可能具有有效期，任务成功后请及时下载并转存
建议显式传递 durationSeconds、resolution 和 generateAudio，不要依赖不同模型版本的隐式默认值
各模型支持的时长、比例、分辨率、音频及图生视频能力以实际可用模型为准