Gemini Omni Flash Preview

本文档介绍如何通过 UniAll.ai API 调用 gemini-omni-flash-preview 生成视频。

示例使用以下地址：

https://api.uniall.ai

如果 UniAll.ai 控制台提供了专属 API 地址，请使用控制台显示的地址。

1. 快速开始

生成接口：

POST /v1beta/interactions

鉴权方式：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

最小文生视频请求：

curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": "A cinematic robot walking through rain at night.",
    "response_format": {
      "type": "video",
      "aspect_ratio": "16:9"
    },
    "generation_config": {
      "video_config": {
        "task": "text_to_video",
        "resolution": "720p",
        "duration_seconds": 4
      }
    }
  }'

2. 支持能力

能力	task	输入要求
文生视频	text_to_video	提示词，不携带图片或视频
图生视频	image_to_video	提示词 + 1 张图片
多参考生成	reference_to_video	提示词 + 图片、视频，或图片与视频的组合

当前不支持：

• 音频参考素材；
• 首帧与尾帧插值；
• 基于历史 interaction_id 的续作或编辑；
• 视频延长；
• Base64、inline_data 或 multipart 文件上传；
• 自定义分辨率、宽度或高度。

3. 请求参数

3.1 顶层参数

参数	类型	必填	说明
model	string	是	固定为 gemini-omni-flash-preview
input	string / object / array	是	提示词及可选的图片、视频 URL
response_format	object	是	输出类型和画面比例
generation_config	object	建议	视频生成参数；建议始终显式传入
timeout_seconds	integer	否	服务端等待结果的最长秒数，默认 300；它不是视频时长

POST /v1beta/interactions 会等待视频生成完成后返回结果。调用方的 HTTP 客户端超时时间应大于 timeout_seconds，视频参考任务建议设置为 600 秒或更长。

3.2 response_format

参数	类型	必填	支持值	默认值
type	string	是	video	无
aspect_ratio	string	否	16:9、9:16	16:9

• 16:9：横屏视频；
• 9:16：竖屏视频。

3.3 generation_config.video_config

参数	类型	必填	支持值	说明
task	string	建议	text_to_video、image_to_video、reference_to_video	建议显式填写，避免输入意图不明确
resolution	string	否	720p	当前唯一支持的分辨率，默认 720p
duration_seconds	integer	否	4、6、8、10	期望视频时长，默认 4

当请求包含视频参考时，模型会结合参考视频自行决定最终输出时长， duration_seconds 不保证与成品视频时长完全一致。需要精确时长时， 请以返回视频文件的实际时长为准。

3.4 task 与素材组合

task	图片	视频	允许的组合
text_to_video	0	0	仅提示词
image_to_video	1	0	恰好 1 张图片
reference_to_video	0–7	0–1	图片、多图、单视频或图片 + 单视频；至少包含一种素材

如果省略 task，系统会根据素材自动判断：

• 没有图片和视频：text_to_video；
• 恰好 1 张图片：image_to_video；
• 多张图片或包含视频：reference_to_video。

为保证调用结果稳定，生产环境建议始终显式传入 task。

4. input 写法

4.1 纯文本

文生视频可以直接传入字符串：

{
  "input": "A paper boat sailing through a neon city during heavy rain."
}

4.2 数组写法

数组写法表达最清晰，推荐用于所有带素材的请求：

{
  "input": [
    {
      "type": "text",
      "text": "Animate the subject with a slow cinematic camera push-in."
    },
    {
      "type": "image",
      "url": "https://example.com/subject.webp"
    },
    {
      "type": "video",
      "url": "https://example.com/motion-reference.mp4"
    }
  ]
}

数组元素：

type	参数	说明
text	text	文本提示词
image	url	可公开访问的图片 URL
video	url	可公开访问的视频 URL

4.3 对象简写

也可以使用对象及 URL 数组：

{
  "input": {
    "text": "Use the references to create one cohesive cinematic shot.",
    "image_urls": [
      "https://example.com/character.png",
      "https://example.com/environment.jpg"
    ],
    "video_urls": [
      "https://example.com/camera-motion.mp4"
    ]
  }
}

支持的对象字段：

参数	类型	说明
text	string	提示词
image_url	string	单张图片 URL
image_urls	string[]	多张图片 URL
video_url	string	单个视频 URL
video_urls	string[]	视频 URL 数组；当前最多 1 个

5. 提示词与素材限制

5.1 提示词

• 所有任务都应提供非空提示词；
• 最大长度为 20000 个字符；
• 多段文本会按顺序合并；
• 建议描述主体、动作、镜头运动、场景、光线、节奏和风格；
• 如果使用参考素材，建议在提示词中明确每个素材的用途。

提示词示例：

Use the first image for the character appearance, the second image for the
environment, and the video for camera motion. Create one continuous cinematic
shot with natural movement and consistent lighting.

5.2 图片

• 支持 JPEG、PNG、WEBP；
• 每张图片最大 20 MB；
• URL 必须能由公网直接访问；
• 不应依赖 Cookie、登录状态或自定义请求头；
• 无视频时最多传入 7 张图片；
• 图生视频必须恰好传入 1 张图片。

5.3 视频

• 每次请求最多 1 个参考视频；
• 视频文件最大 100 MB；
• 输入视频最长 30 秒；
• 推荐使用兼容性较好的 MP4 文件；
• 参考素材使用视频开头最多 10 秒的内容；
• 视频 URL 必须能由公网直接访问。

5.4 参考素材配额

每张图片占 1 个素材单位，每个视频占 2 个素材单位，总计不能超过 7 个单位：

图片数量 + 视频数量 × 2 <= 7

图片数	视频数	是否允许
7	0	是
5	1	是
6	1	否
0	1	是
0	2	否

6. 请求示例

以下示例均使用推荐的显式参数写法。

6.1 横屏文生视频

curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": "A wide cinematic shot of an astronaut walking through a field of glowing flowers at dusk, gentle wind, slow dolly-in camera movement.",
    "response_format": {
      "type": "video",
      "aspect_ratio": "16:9"
    },
    "generation_config": {
      "video_config": {
        "task": "text_to_video",
        "resolution": "720p",
        "duration_seconds": 6
      }
    },
    "timeout_seconds": 600
  }'

6.2 竖屏文生视频

curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": [
      {
        "type": "text",
        "text": "Vertical fashion film, a model walking through a minimalist white gallery, soft shadows, smooth handheld camera, premium editorial style."
      }
    ],
    "response_format": {
      "type": "video",
      "aspect_ratio": "9:16"
    },
    "generation_config": {
      "video_config": {
        "task": "text_to_video",
        "resolution": "720p",
        "duration_seconds": 10
      }
    },
    "timeout_seconds": 600
  }'

6.3 单图生成视频

curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": [
      {
        "type": "image",
        "url": "https://example.com/portrait.webp"
      },
      {
        "type": "text",
        "text": "Keep the character appearance consistent. Add subtle breathing and blinking, hair moving gently in the wind, and a slow camera push-in."
      }
    ],
    "response_format": {
      "type": "video",
      "aspect_ratio": "9:16"
    },
    "generation_config": {
      "video_config": {
        "task": "image_to_video",
        "resolution": "720p",
        "duration_seconds": 4
      }
    },
    "timeout_seconds": 600
  }'

6.4 多图角色与场景参考

curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": {
      "text": "Use the first image for the character, the second for clothing, and the third for the environment. Create one continuous shot of the character entering the cafe and looking toward the camera.",
      "image_urls": [
        "https://example.com/character.png",
        "https://example.com/outfit.jpg",
        "https://example.com/cafe.webp"
      ]
    },
    "response_format": {
      "type": "video",
      "aspect_ratio": "16:9"
    },
    "generation_config": {
      "video_config": {
        "task": "reference_to_video",
        "resolution": "720p",
        "duration_seconds": 8
      }
    },
    "timeout_seconds": 600
  }'

6.5 单视频动作参考

curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": [
      {
        "type": "video",
        "url": "https://example.com/dance-motion.mp4"
      },
      {
        "type": "text",
        "text": "Create a cinematic dancer performance using the reference for body movement and rhythm. Use dramatic blue stage lighting and a slowly orbiting camera."
      }
    ],
    "response_format": {
      "type": "video",
      "aspect_ratio": "16:9"
    },
    "generation_config": {
      "video_config": {
        "task": "reference_to_video",
        "resolution": "720p",
        "duration_seconds": 8
      }
    },
    "timeout_seconds": 600
  }'

6.6 图片与视频混合参考

curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": {
      "text": "Use the character image for appearance, the city image for the environment, and the video for camera motion. Keep the character identity and clothing consistent throughout the shot.",
      "image_urls": [
        "https://example.com/character.png",
        "https://example.com/night-city.jpg"
      ],
      "video_urls": [
        "https://example.com/camera-reference.mp4"
      ]
    },
    "response_format": {
      "type": "video",
      "aspect_ratio": "16:9"
    },
    "generation_config": {
      "video_config": {
        "task": "reference_to_video",
        "resolution": "720p",
        "duration_seconds": 10
      }
    },
    "timeout_seconds": 600
  }'

6.7 Python 调用

import requests

api_url = "https://api.uniall.ai/v1beta/interactions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "model": "gemini-omni-flash-preview",
    "input": [
        {
            "type": "image",
            "url": "https://example.com/product.png",
        },
        {
            "type": "text",
            "text": (
                "Create a premium product film with a slow 360-degree camera "
                "move, soft studio reflections, and a dark background."
            ),
        },
    ],
    "response_format": {
        "type": "video",
        "aspect_ratio": "16:9",
    },
    "generation_config": {
        "video_config": {
            "task": "image_to_video",
            "resolution": "720p",
            "duration_seconds": 6,
        }
    },
    "timeout_seconds": 600,
}

response = requests.post(
    api_url,
    headers=headers,
    json=payload,
    timeout=660,
)
response.raise_for_status()

result = response.json()
print(result["interaction_id"])
print(result["response"]["video"]["uri"])

6.8 JavaScript 调用

const response = await fetch("https://api.uniall.ai/v1beta/interactions", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gemini-omni-flash-preview",
    input: "A tiny red train crossing a snowy mountain bridge at sunrise.",
    response_format: {
      type: "video",
      aspect_ratio: "16:9",
    },
    generation_config: {
      video_config: {
        task: "text_to_video",
        resolution: "720p",
        duration_seconds: 4,
      },
    },
    timeout_seconds: 600,
  }),
});

const result = await response.json();
if (!response.ok) {
  throw new Error(result.error?.message ?? "Video generation failed");
}

console.log(result.interaction_id);
console.log(result.response.video.uri);

7. 成功响应

成功时返回一个 Gemini Interactions 风格的结果：

{
  "interaction_id": "task_xxx",
  "model": "gemini-omni-flash-preview",
  "response": {
    "video": {
      "uri": "https://api.uniall.ai/media/generated-video.mp4"
    }
  }
}

字段	说明
interaction_id	本次生成的唯一标识，可用于查询
model	实际调用的公共模型名称
response.video.uri	生成视频的访问地址

建议及时下载并保存生成结果，不要假设视频 URL 永久有效。

8. 任务状态与结果

POST /v1beta/interactions 通常会等待交互结果。需要后续查询时，保存 interaction_id 并调用 GET /v1/videos/generations/{interaction_id}，不要使用默认任务路径。公共终态、错误结构和结果字段见视频生成概览。

9. 错误响应

错误响应采用统一结构：

{
  "error": {
    "code": 400,
    "message": "`duration_seconds` must be one of 4, 6, 8, or 10",
    "status": "INVALID_ARGUMENT"
  }
}

常见错误：

HTTP 状态码	error.status	说明
400	INVALID_ARGUMENT	参数、素材数量或任务类型不符合要求
400	FAILED_PRECONDITION	请求内容未通过安全检查
401	UNAUTHENTICATED	API Key 缺失或无效
404	NOT_FOUND	模型或查询标识不存在
429	RESOURCE_EXHAUSTED	请求频率过高
503	UNAVAILABLE	服务暂时不可用
504	DEADLINE_EXCEEDED	在 timeout_seconds 内未获得生成结果

10. 计费说明

价格与计费规则可能调整，请以 UniAll.ai 控制台当前显示的模型价格和用量记录为准。对账或联系支持时，请保留本次请求的 interaction_id。

11. 调用建议

• 显式传入 task、resolution、duration_seconds 和 aspect_ratio；
• 素材 URL 使用 HTTPS，并确认在无登录状态下可以直接下载；
• 客户端 HTTP 超时应比 timeout_seconds 多预留 30–60 秒；
• 视频参考任务的最终时长以成品文件为准；
• 多参考任务中，应在提示词里说明每个素材的用途；
• 收到 429、503 时使用指数退避重试，不要高频立即重试；
• 不要在日志、前端代码或公开仓库中暴露 API Key。