Skip to main content
本文将介绍 Gemini Videos Generation API 的对接说明，它可以通过输入文本提示词（以及可选的参考图片）来生成 Google Gemini（omni-flash）视频。

​
申请流程

要使用 Gemini Videos Generation API，首先到 Ace Data Cloud 控制台 获取您的 API Token，留作备用。 如果你尚未登录或注册，会自动跳转到登录页面邀请你注册和登录，完成后会自动返回当前页面。 一个 API Token 即可调用平台所有服务，无需为每个服务单独申请。 首次申请会赠送免费额度，可免费体验；额度不足时可在 控制台 充值通用余额。
📘 完整文档：Gemini Videos Generation API →

​
基本使用

首先了解下基本的使用方式，输入提示词 prompt、模型 model 以及宽高比 aspect_ratio，便可生成对应的视频。 可以看到这里我们设置了 Request Headers，包括：
  • accept：想要接收怎样格式的响应结果，这里填写为 application/json，即 JSON 格式。
  • authorization：调用 API 的密钥，申请之后可以直接下拉选择。
另外设置了 Request Body，包括：
  • prompt：描述想要生成视频内容的文本提示词，必填。
  • model：生成视频的模型，目前仅支持 omni-flash，默认即为 omni-flash。
  • aspect_ratio：生成视频的宽高比，可选 16:9（横屏）或 9:16（竖屏），默认 16:9。
  • resolution：可选的输出分辨率，可选 720p 或 1080p，默认 720p。
  • image_urls：可选的参考图片链接数组，用于引导视频生成，留空项会被忽略。当使用 video_urls 进行视频编辑时，本参数必填（至少一张）。
  • video_urls：可选的参考视频链接数组（最多 1 个），用于视频编辑 / 视频参考；提供时必须同时提供至少一张 image_urls。
  • callback_url：异步回调地址，设置后 API 会立即返回 task_id，任务完成时将结果 POST 到该地址。
  • async：可选，设为 true 时接口立即返回 task_id，无需提供 callback_url，随后通过对应的任务查询接口轮询获取结果。
点击「Try」按钮即可进行测试，得到的结果类似如下：
返回结果一共有多个字段，介绍如下：
  • success：本次视频生成请求是否成功。
  • task_id：本次视频生成任务的 ID。
  • trace_id：本次请求的跟踪 ID，用于排查问题。
  • data：生成的视频结果列表。
    • id：生成视频的唯一标识。
    • video_url：生成视频的链接地址（state 为 pending 时为 null）。
    • state：视频生成任务的状态，可选 pending / succeeded / failed。
    • aspect_ratio：该视频的宽高比，与请求参数一致。
    • prompt：生成该视频所使用的提示词。
同步返回时，顶层还会附带 started_at、finished_at、elapsed（耗时，秒）以及 cost（本次扣费，单位 Credit）等字段。 我们只需要根据结果中 data 的 video_url 链接地址获取生成的视频即可。 对应的 CURL 代码如下：
对应的 Python 代码如下：

​
图生视频

如果想基于参考图片生成视频，可以在 image_urls 中传入一个或多个图片链接，用于引导视频生成：

​
视频编辑 / 参考视频（输入视频，生成视频）

支持直接「输入一段视频，生成一段新视频」：在 video_urls 中传入一个参考视频链接（最多 1 个），并同时在 image_urls 中提供至少一张参考图（上游硬性要求），再用 prompt 描述想要的编辑效果（改风格、换场景、增删元素等）。 下面是一个完整的真实示例——把一段阳光沙滩的视频改成大雪纷飞的冬日场景，同时保留沙滩、椰树和小船的布局。视频编辑耗时较长（本例约 6.5 分钟），因此用 async: true 异步提交：
提交后接口立即返回 task_id：
之后用该 task_id 作为 id 轮询 Gemini Tasks API，任务完成后即可拿到生成的新视频（这是本示例的真实返回结果）：
如需更高清的结果，可将 resolution 设为 1080p（其余参数不变）。
提示：示例中的输入 / 输出媒体链接均为真实生成结果。平台生成的视频、图片链接有保存期限，过期后会失效，请在拿到结果后及时下载保存到自己的存储。
注意：参考视频最多 1 个；且提供 video_urls 时必须提供至少一张 image_urls，否则会返回如下参数错误：

​
异步回调

视频生成需要一定的处理时间。如果不希望保持长连接等待，可以传入 callback_url，此时 API 会立即返回 task_id，任务完成后会将最终结果 POST 到该地址：
立即返回的结果如下：

​
查询任务结果

如果使用了异步回调或希望主动查询任务状态，可以通过 Gemini Tasks API（POST https://api.acedata.cloud/gemini/tasks）根据 task_id 查询任务的最新状态与结果。请求体中传入创建视频时返回的 task_id 作为 id：
任务完成后返回的结果类似如下，response.data 的结构与同步生成时一致（生成中时 state 为 pending、video_url 为 null）：

​
错误处理

当请求出现问题时，API 会返回对应的错误码与说明，常见的如下：
  • 400：请求参数有误，例如缺少 prompt 或 aspect_ratio 取值非法。
  • 401：鉴权失败，token 无效或与 API 不匹配。
  • 403：余额不足，或提示词命中内容审核被拒绝。
  • 500：服务器内部错误或上游生成失败。