Gemini Omni API 接入文档

使用 VezAPI 密钥接入 Gemini Omni。下列操作共用同一个账号余额和鉴权方式。

服务地址： https://api.vezapi.com
请求头使用 Authorization: Bearer YOUR_VEZAPI_KEY。每次提交使用唯一的 Idempotency-Key，查询同一笔提交时才复用。

Gemini Omni Audio 生语音

POST/api/v1/omni/audio/create

参数	类型	说明与限制
`audio_id` 必填	`string`	枚举语音ID，用于选择预设语音角色。 achernar - 女声，柔和，高音调 achird - 男声，友好，中音调 algenib - 男声，沙哑，低音调 algieba - 男声，随和，中低音调 alnilam - 男声，沉稳，中低音调 aoede - 女声，轻快，中音调 autonoe - 女声，明亮，中音调 callirrhoe - 女声，随和，中音调 charon - 男声，知性，低音调 despina - 女声，流畅，中音调 enceladus - 男声，气声，低音调 erinome - 女声，清晰，中音调 fenrir - 男声，活泼，偏年轻音调 gacrux - 女声，成熟，中音调 iapetus - 男声，清晰，中低音调 kore - 女声，干练，中音调 laomedeia - 女声，欢快，中高音调 leda - 女声，年轻，中高音调 orus - 男声，沉稳，中低音调 puck - 男声，欢快，中音调 pulcherrima - 无性别，前置感，中高音调 rasalgethi - 男声，知性，中音调 sadachbia - 男声，生动，低音调 sadaltager - 男声，博学，中音调 schedar - 男声，平稳，中低音调 sulafat - 女声，温暖，中音调 umbriel - 男声，流畅，低音调 vindemiatrix - 女声，温柔，中音调 zephyr - 女声，明亮，中高音调 zubenelgenubi - 男声，随性，中低音调
`name` 必填	`string`	语音名称，最大长度为 `210` 字符。 `maxLength: 210`
`voice_description` 可选	`string`	语音特征描述，用于定义声音的音色、风格、语速、情绪等，最大长度为 `20000` 字符。 `maxLength: 20000`
`example_dialogue` 可选	`string`	对话示例，例如“你好,我是Adam”，最大长度为 `120` 字符。 `maxLength: 120`

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/omni/audio/create' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "audio_id": "achernar",
  "name": "Your prompt"
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`code` 可选	`integer`	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying).
`data` 可选	`object`
`data.audioId` 可选	`string`
`data.name` 可选	`string`
`msg` 可选	`string`

Gemini Omni Character 生角色

POST/api/v1/omni/character/create

参数	类型	说明与限制
`descriptions` 必填	`string`	角色描述，用于说明角色的外观、身份、风格、服饰或性格设定。
`image_urls` 必填	`array`	角色参考图片 URL 数组。支持最多 2 张图片。索引 0 为头像图片，索引 1 为全身图片。全身图片为可选，但如果提供，则索引 0 处必须存在头像图片。图片限制： - 每张图片大小不得超过 `20MB` - 请使用可公开访问的图片 URL `minItems: 1` `maxItems: 2`
`audio_ids` 可选	`array`	由 `gemini-omni-audio` 接口生成的音频 ID 数组。可用于为角色补充声音特征、语气或人设参考。
`character_name` 可选	`string`	角色名称

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/omni/character/create' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "descriptions": "A young female character with short silver hair and a futuristic utility jacket, calm, agile, and strongly cyberpunk in style.",
  "image_urls": [
    "https://example.com/input.png",
    "https://example.com/input.png"
  ]
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`code` 可选	`integer`	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying).
`data` 可选	`object`
`data.characterName` 可选	`string`
`data.imageUrl` 可选	`string`
`data.characterId` 可选	`string`
`data.bodyImageUrl` 可选	`string`
`msg` 可选	`string`

Gemini Omni 生视频

POST/api/v1/jobs/createTask

模型标识： gemini-omni-video

参数	类型	说明与限制
`model` 必填	`string`	用于生成任务的模型名称。该字段为必填项。此接口必须使用 `gemini-omni-video` 模型。可选值：`"gemini-omni-video"` 默认：`"gemini-omni-video"`
`callBackUrl` 可选	`string`	任务完成通知的回调 URL。该参数为可选项。如果提供，当任务完成时，无论成功或失败，系统都会向该 URL 发送 POST 请求。如果未提供，则不会发送回调通知。
`input` 必填	`object`	多模态视频生成任务的输入参数。
`input.prompt` 必填	`string`	视频提示词，用于描述目标视频的画面内容、风格、镜头语言或角色行为。 `maxLength: 20000`
`input.image_urls` 可选	`array`	图片地址数组。可上传多张参考图片，用于提供角色、场景、风格或分镜参考。图片限制： - 单个文件大小不超过 `20MB` - 请使用可公开访问的图片 URL - 最大7张图
`input.audio_ids` 可选	`array`	由 `gemini-omni-audio` 接口生成的音频 ID 数组。用于为视频提供旁白、对白、配乐或声音参考。最多3个。
`input.video_list` 可选	`array`	视频片段数组。每个元素描述一个可参与生成的视频素材及其截取时间范围。视频限制： - 单个文件大小不超过 `100MB` - 视频时长不超过 `30s` - `ends` 应大于 `start` - 结束与起始时间之差不超过`10s` - 最多1个，占用两张图
`input.video_list[].url` 必填	`string`	视频地址。单个视频文件大小不超过 `100MB`，视频时长不超过 `30s`。
`input.video_list[].start` 必填	`number`	起始时间，单位为秒。 `minimum: 0`
`input.video_list[].ends` 必填	`number`	结束时间，单位为秒。应大于 `start`。结束与起始时间之差不超过10秒 `minimum: 0`
`input.character_ids` 可选	`array`	由 `gemini-omni-character` 接口生成的角色 ID 数组。用于为视频提供角色外观、身份或人物参考。最多 3 个角色 ID。每个占 1 个图片槽位（用肖像+全身两张图创建的占 2 个）。总槽位（图片数 + 视频数×2 + 角色槽位）≤ 7。
`input.duration` 必填	`string`	生成视频的时长，单位为秒。可选值为 4、6、8、10。该参数仅在无视频输入时生效；如使用视频输入，输出时长由模型决定，duration 参数将被忽略。注意：当提供视频输入时，输出时长由模型自动确定。此时 duration 参数将不会生效。可选值：`"4", "6", "8", "10"`
`input.aspect_ratio` 可选	`string`	生成视频的画面宽高比。`16:9` 为横屏视频，`9:16` 为竖屏视频。可选值：`"16:9", "9:16"`
`input.resolution` 可选	`string`	生成视频的分辨率。可选值为 720p、1080p、4k。可选值：`"720p", "1080p", "4k"` 默认：`"720p"`
`input.seed` 可选	`integer`	随机种子。取值范围：[0, 2147483647]。如果不指定，系统会自动生成一个 seed。固定 seed 可以提高结果的可复现性，但由于模型本身具有随机性，结果仍可能存在差异。

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "gemini-omni-video",
  "input": {
    "prompt": "Create a futuristic night city short film with a slow push-in shot as the character walks out from a neon-lit street.",
    "duration": "8",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`code` 可选	`integer`	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值：`200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505`
`msg` 可选	`string`	Response message, error description upon failure
`data` 必填	`object`
`data.taskId` 必填	`string`	The task ID can be used with the "Get Task Details" endpoint to query the task status.

任务状态与回调

异步任务请保存返回的 taskId。调用 GET /api/v1/jobs/recordInfo?taskId=... 查询，或在创建时设置 callBackUrl。只有任务所属账号可以查询任务或基于任务创建派生资源。

超时可能表示请求已经受理。请在控制台查看原请求，不要自动新建任务。回调可能重试并重复到达，请使用 X-VezAPI-Event-Id 去重。

文件、日志与计费

生成媒体通常随上游保留 14 天，上传文件在 24 小时后失效。请在过期前保存所需文件。VezAPI 仅流式转发已登记资源，不提供永久作品库。请求日志保留两个自然月。

调用前预留积分，最终按实际优惠扣分 1:1 结算。用量不明时暂停新付费请求。若保护其他任务预留后余额不足以结算，会保留待结算记录，补足余额后再扣费；模型用量不会将钱包扣成负数。按时长计价的输入文件由服务端读取时长，读取失败时不提交模型任务。