Gemini Omni API documentation

Integrate Gemini Omni with your VezAPI key. The operations below share the same authentication and account balance.

Base URL: https://api.vezapi.com
Send Authorization: Bearer YOUR_VEZAPI_KEY. Use a unique Idempotency-Key for each submission; reuse it only when checking the same request.

Gemini Omni Audio

POST/api/v1/omni/audio/create

Parameter	Type	Description & constraints
`audio_id` required	`string`	Enum voice ID, used to select a preset voice character. achernar - female, soft, high pitch achird - male, friendly, mid pitch algenib - male, raspy, low pitch algieba - male, easygoing, mid-low pitch alnilam - male, steady, mid-low pitch aoede - female, brisk, mid pitch autonoe - female, bright, mid pitch callirrhoe - female, easygoing, mid pitch charon - male, intellectual, low pitch despina - female, smooth, mid pitch enceladus - male, breathy, low pitch erinome - female, clear, mid pitch fenrir - male, lively, younger pitch gacrux - female, mature, mid pitch iapetus - male, clear, mid-low pitch kore - female, capable, mid pitch laomedeia - female, cheerful, mid-high pitch leda - female, young, mid-high pitch orus - male, steady, mid-low pitch puck - male, cheerful, mid pitch pulcherrima - genderless, forward, mid-high pitch rasalgethi - male, intellectual, mid pitch sadachbia - male, vivid, low pitch sadaltager - male, knowledgeable, mid pitch schedar - male, smooth, mid-low pitch sulafat - female, warm, mid pitch umbriel - male, smooth, low pitch vindemiatrix - female, gentle, mid pitch zephyr - female, bright, mid-high pitch zubenelgenubi - male, casual, mid-low pitch
`name` required	`string`	Voice name. Maximum length: `210` characters.
`voice_description` optional	`string`	Voice characteristic description used to define timbre, style, speaking rate, emotion, and other traits. Maximum length: `20000` characters.
`example_dialogue` optional	`string`	Example dialogue, such as "Hello, I am Adam". Maximum length: `120` characters.

Request example

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"
}'

Responses and errors

HTTP 200

Request successful

Parameter	Type	Description & constraints
`code` optional	`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` optional	`object`
`data.audioId` optional	`string`
`data.name` optional	`string`
`msg` optional	`string`

Gemini Omni Character

POST/api/v1/omni/character/create

Parameter	Type	Description & constraints
`descriptions` required	`string`	Character description used to define the appearance, identity, style, clothing, or personality of the character.
`image_urls` required	`array`	Array of character reference image URLs. Up to 2 images are supported. Index 0 is the portrait image, and index 1 is the body image. The body image is optional, but if provided, the portrait image must be present at index 0. Image limits: - Each image must be no larger than `20MB` - Use a publicly accessible image URL `minItems: 1` `maxItems: 2`
`audio_ids` optional	`array`	Array of audio IDs generated by the `gemini-omni-audio` endpoint. These can be used to provide voice traits, tone, or persona guidance for the character.
`character_name` optional	`string`	Character name

Request example

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"
  ]
}'

Responses and errors

HTTP 200

Request successful

Parameter	Type	Description & constraints
`code` optional	`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` optional	`object`
`data.characterName` optional	`string`
`data.imageUrl` optional	`string`
`data.characterId` optional	`string`
`data.bodyImageUrl` optional	`string`
`msg` optional	`string`

Gemini Omni Video

POST/api/v1/jobs/createTask

Model IDs: gemini-omni-video

Parameter	Type	Description & constraints
`model` required	`string`	The model name used for generation. This field is required. This endpoint must use the `gemini-omni-video` model. Values: `"gemini-omni-video"` Default: `"gemini-omni-video"`
`callBackUrl` optional	`string`	Callback URL for task completion notifications. Optional parameter. If provided, the system will send a POST request to this URL when the task completes, whether it succeeds or fails. If omitted, no callback notification will be sent.
`input` required	`object`	Input parameters for the multimodal video generation task.
`input.prompt` required	`string`	Video prompt used to describe the target content, style, camera language, or character actions in the generated video. `maxLength: 20000`
`input.image_urls` optional	`array`	Array of image URLs. You can provide one or more reference images for characters, scenes, styles, or storyboard guidance. Image limits: - Each file must be no larger than `20MB` - Use publicly accessible image URLs - Max 7 images
`input.audio_ids` optional	`array`	Array of audio IDs generated by the `gemini-omni-audio` endpoint. Useful for narration, dialogue, music, or audio guidance in the generated video. Max 3 items.
`input.video_list` optional	`array`	Array of video clips. Each item defines a source video and the trim range to use during generation. Video limits: - Each file must be no larger than `100MB` - Video duration must not exceed `30s` - `ends` should be greater than `start` - The difference between the end time and the start time must not exceed `10s`. - Max 1 items. Equal 2 images
`input.video_list[].url` required	`string`	Video URL. Each source video file must be no larger than `100MB` and no longer than `30s`.
`input.video_list[].start` required	`number`	Start time in seconds. `minimum: 0`
`input.video_list[].ends` required	`number`	End time in seconds. It should be greater than `start`.The difference between the end time and the start time must not exceed 10s `minimum: 0`
`input.character_ids` optional	`array`	An array of character IDs generated by the `gemini-omni-character` API. Used to provide character appearance, identity, or person references for the video. Up to 3 character IDs. Each uses 1 image slot (2 if created with portrait + body images). Total slots (images + videos × 2 + character slots) ≤ 7.
`input.duration` required	`string`	The duration of the generated video in seconds. Available values are 4, 6, 8, and 10. When video input is provided, the output duration is determined by the model automatically. This duration parameter will not take effect.Note: when video input is provided, the output duration is determined by the model automatically. This duration parameter will not take effect. Values: `"4", "6", "8", "10"`
`input.aspect_ratio` optional	`string`	The aspect ratio of the generated video. `16:9` is landscape, and `9:16` is portrait. Values: `"16:9", "9:16"`
`input.resolution` optional	`string`	The resolution of the generated video. Available values are 720p, 1080p, and 4k. Values: `"720p", "1080p", "4k"` Default: `"720p"`
`input.seed` optional	`integer`	Random seed. Range: [0, 2147483647]. If not specified, the system generates a seed automatically. Fixing the seed can improve reproducibility, but results may still vary due to the model’s stochasticity.

Request example

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"
  }
}'

Responses and errors

HTTP 200

Request successful

Parameter	Type	Description & constraints
`code` optional	`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). Values: `200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505`
`msg` optional	`string`	Response message, error description upon failure
`data` required	`object`
`data.taskId` required	`string`	The task ID can be used with the "Get Task Details" endpoint to query the task status.

Task status and callbacks

For asynchronous tasks, keep the returned taskId. Query GET /api/v1/jobs/recordInfo?taskId=... or provide callBackUrl when creating the task. Only the account that created a task can access it or derive new resources from it.

A timeout can mean the submission was accepted. Inspect the existing request in your dashboard; do not create another task automatically. Callback delivery is retried and may arrive more than once. Deduplicate with X-VezAPI-Event-Id.

Files, logs and billing

Generated media normally follows a 14-day provider lifetime; uploaded files expire after 24 hours. Save the files you need before expiration. VezAPI streams registered files without keeping a permanent media library. Request logs are retained for two calendar months.

Credits are reserved before submission. Final deductions match actual discounted consumption one for one. Unknown usage pauses new paid requests. If available funds cannot cover final usage while protecting other reservations, settlement stays pending until funded; model usage cannot make the wallet negative. Time-based inputs require server-side metadata reads; a failed read prevents submission.