跳转到主要内容
POST
文生视频与图生视频支持 3–15 整秒,默认 10 秒;首尾帧插值和续写新增部分最长 10 秒。编辑时忽略 duration,输出时长跟随源视频。有视频输入时默认编辑,续写必须显式传 "omni_reference_task_type": "extend"。

认证

string
必填
使用 Bearer Token 认证,在 API Key 管理页面 获取密钥。提交请求使用 Content-Type: application/json。

请求参数

string
必填
固定为 gemini-omni-1.2-flash。
string
必填
必填文本指令。文生视频描述场景;图生视频、编辑和续写描述动作、风格或修改要求。即使提供参考图、首尾帧、视频或 extend_from_task_id,也必须传入 prompt;缺少时返回 HTTP 400。
integer
默认值:"10"
文生视频与图生视频的输出时长,整数 3–15,默认 10。首尾帧插值和续写仅支持 3–10 秒;续写时表示新增片段的时长,返回的视频包含原片和新增片段。编辑视频时忽略 duration,输出时长跟随源视频。参数超出允许范围会使任务以 invalid_duration 失败。
string
默认值:"720p"
360p / 720p / 1080p / 4k,不区分大小写,2160p 按 4k 处理。1080p 和 4k 为上采样输出。分辨率影响输出 token 用量和预扣额度;其他值会使任务以 invalid_resolution 失败。
string
默认值:"16:9"
仅支持 16:9(横屏,默认)和 9:16(竖屏);其他值按 16:9 处理。
string[]
参考图片数组,仅支持公网可访问的 HTTP(S) 图片直链,不支持 Data URL 或 Base64。单张图默认作为起始画面,多张图作为主体参考。所有图片与首尾帧合计最多 10 张;角色参考建议最多 2 个角色、每个角色最多 3 张,共不超过 6 张。
string
首帧图片。单独传入时以此图为起始画面;与 last_frame_image 同传时进行首尾帧插值。仅支持公网可访问的 HTTP(S) 图片直链。
string
尾帧图片,必须与 first_frame_image 同传,否则任务以 invalid_frame_images 失败。首尾帧应使用相同比例,并与 aspect_ratio 匹配。仅支持公网可访问的 HTTP(S) 图片直链。
object[]
带角色的图片数组,是首尾帧字段的等价写法。首尾帧使用直接字段或此数组二选一即可;所有实际使用的图片合计最多 10 张。
string[]
待编辑或续写的视频数组,最多 1 段,时长不超过 15 秒。仅支持公网可访问的 HTTP(S) 视频直链,不支持 Data URL 或 Base64。有视频输入时默认编辑。
string
默认值:"auto"
任务类型:auto(默认,按输入自动判断)/ edit(编辑)/ extend(续写)/ reference(多图参考)。也接受 text_to_video / image_to_video / reference_to_video。省略或使用 auto 时,video_urls 和 extend_from_task_id 默认执行编辑;续写必须显式设置为 extend。
string
引用自己的上一次生成任务 ID,无需重新上传结果视频。默认进行编辑;配合 "omni_reference_task_type": "extend" 时在片尾追加,新增片段最长 10 秒。

能力与限制

  • 输出为 24fps 视频,包含对白、音乐或音效;可在 prompt 中描述声音。
  • 不支持音频输入、system prompt、temperature 或负向提示词参数;负向要求请直接写入 prompt。
  • 上游地区限制:EEA、瑞士和英国不支持编辑或续写上传的视频,也不支持含未成年人的图片编辑。
  • 所有输出包含 SynthID 不可见水印。

使用示例

以下 JSON 均提交到 POST /v1/videos/generations。将示例素材 URL 和任务 ID 替换为自己的可用素材。

15 秒 4K 竖屏视频

图生视频与多主体参考

首尾帧插值

使用图片角色声明首尾帧

视频编辑

编辑视频时,输出时长跟随源视频,duration 不生效。 编辑建议使用简短、明确的指令。只修改局部时,可加入 Keep everything else the same。

基于已有任务续写

续写上传的视频时,将 extend_from_task_id 换为 video_urls,并保留 "omni_reference_task_type": "extend"。返回的视频为原片加上片尾新增片段;duration 控制新增时长,最长 10 秒,只按新增秒数计费。例如 5 秒原片加上 duration: 4,返回约 9 秒的视频。

提交响应与任务查询

提交成功返回 HTTP 200,从 data[0].task_id 获取任务号。通过任务查询接口每 5–10 秒轮询一次,直到 completed 或 failed。整体等待超时建议设为 10 分钟;客户端超时后继续查询原任务,避免重复提交。
耗时仅供参考:360p、15 秒视频约需 30 秒;4K、15 秒视频约需 5 分钟,实际以任务状态为准。
查询响应的 data 是任务对象。data.result.videos[0].url 是链接数组,首个视频地址为 data.result.videos[0].url[0],可下载或播放;长期保存请自行归档。data.cost 是最终结算金额(美元)。

计费与预扣

按 token 计费,分辨率影响每秒输出 token 用量。文生视频与图生视频由 duration 指定输出时长;编辑时忽略该参数,输出时长跟随源视频;续写时该参数只控制新增片段的时长。实际价格以 APIMart 价格页面 为准。 提交时按分辨率和 max(10, duration) 秒预扣额度;带视频输入时按 15 秒估算。预扣额度不等于最终费用,成功后按实际用量多退少补,最终读取 data.cost。 续写只按新增秒数计费。失败不计费;余额不足以覆盖预扣额度时返回 HTTP 402。

错误处理

参数类错误(invalid_* / unsupported_*)会使任务立即变为 failed,且不扣费。提交成功后仍需查询任务状态。

常见问题

已经提供图片或视频,还需要传 prompt 吗?

需要。所有模式都必须传入 prompt,包括图生视频、首尾帧插值、编辑、续写以及通过 extend_from_task_id 复用视频。缺少该字段会返回 HTTP 400。

支持直接传 Base64 图片或视频吗?

不支持。image_urls、first_frame_image、last_frame_image、image_with_roles[].url 和 video_urls 仅支持公网可访问的 HTTP(S) 直链。不能传入 data:image/...、data:video/... 或裸 Base64 字符串。