Referência de API
Gemini Omni Texto para vídeo
Use o endpoint de texto para vídeo para criar uma Task assíncrona.
01
Visão geral
Use o endpoint de texto para vídeo com um modelo compatível. Use o Task ID retornado para recuperar seu estado, ou forneça callback_url para as entregas documentadas abaixo.
Início rápido
- Crie uma Chave de API e defina-a como RUNAPI_API_KEY.
- Escolha um modelo compatível e envie uma requisição POST cujo corpo corresponda ao schema desse modelo.
- Armazene o ID da tarefa retornado e, em seguida, faça polling até atingir um estado terminal ou trate os callbacks documentados abaixo.
Endpoint
- URL base
https://runapi.ai- Versão da API
v1- Autenticação
Authorization: Bearer YOUR_API_TOKEN
02
Modelos suportados
Abra uma página de modelo para ver preços atuais, limites de taxa e detalhes de uso comercial.
03
Corpo JSONEsquema de solicitação
Os campos e valores permitidos dependem do modelo selecionado. Quando fornecido, callback_url recebe as entregas da Task documentadas abaixo.
gemini-omni-flash-1-116 campos
aspect_ratiostring
Opcional
Proporção de aspecto da saída.
Valores permitidos:16:9, 9:16
audio_idsarray
Opcional
IDs de predefinição de áudio retornados por create-audio.
Limite de itens:3
callback_urlstring
Opcional
URL de webhook para entrega de Task em estado terminal.
character_idsarray
Opcional
IDs de personagens retornados por create-character; personagens de imagem dupla consomem duas das sete unidades de referência compartilhadas.
Limite de itens:3
duration_secondsinteger
Obrigatório
Duração da saída em segundos.
Valores permitidos:4, 6, 8, 10
first_frame_image_urlstring
Opcional
URL pública de imagem do primeiro frame; mutuamente exclusiva com imagens de referência, IDs de áudio, clipes de vídeo e IDs de personagens.
last_frame_image_urlstring
Opcional
URL de imagem do último quadro pública; requer first_frame_image_url.
modelstring
Opcional
Slug do modelo; usa gemini-omni-text-to-video por padrão quando omitido.
output_resolutionstring
Opcional
Resolução de saída.
Valores permitidos:360p, 720p, 1080p, 4k
Padrão: 720p
promptstring
Obrigatório
Prompt de geração de vídeo.
Limite:20000
reference_image_urlsarray
Opcional
URLs de imagens de referência públicas; imagens, clipes de vídeo e personagens compartilham um limite de sete unidades de referência.
Limite de itens:7
seedinteger
Opcional
Semente de geração determinística.
Intervalo:0 - 2147483647
video_listarray
Opcional
Clipes de vídeo de origem; cada clipe consome duas unidades de referência.
Limite de itens:1
video_list[].endsnumber
Obrigatório
Tempo de término do clipe em segundos; deve ser maior que o início e no máximo 10 segundos após o início.
Limite:0
video_list[].startnumber
Obrigatório
Tempo de início do clipe em segundos.
Limite:0
video_list[].urlstring
Obrigatório
URL de vídeo de origem pública.
gemini-omni-flash-preview5 campos
aspect_ratiostring
Opcional
Proporção de aspecto da saída.
Valores permitidos:16:9, 9:16
Padrão: 16:9
callback_urlstring
Opcional
URL de webhook para entrega de Task em estado terminal.
modelstring
Opcional
Slug do modelo; usa gemini-omni-text-to-video por padrão quando omitido.
output_resolutionstring
Opcional
Resolução de saída.
Valores permitidos:720p
Padrão: 720p
promptstring
Obrigatório
Prompt de geração de vídeo.
Limite:20000
gemini-omni-text-to-video14 campos
aspect_ratiostring
Opcional
Proporção de aspecto da saída.
Valores permitidos:16:9, 9:16
audio_idsarray
Opcional
IDs de predefinição de áudio retornados por create-audio.
Limite de itens:3
callback_urlstring
Opcional
URL de webhook para entrega de Task em estado terminal.
character_idsarray
Opcional
IDs de personagens retornados por create-character; personagens de imagem dupla consomem duas das sete unidades de referência compartilhadas.
Limite de itens:3
duration_secondsinteger
Obrigatório
Duração da saída em segundos.
Valores permitidos:4, 6, 8, 10
modelstring
Opcional
Slug do modelo; usa gemini-omni-text-to-video por padrão quando omitido.
Padrão:gemini-omni-text-to-video
output_resolutionstring
Opcional
Resolução de saída.
Valores permitidos:720p, 1080p, 4k
Padrão: 720p
promptstring
Obrigatório
Prompt de geração de vídeo.
Limite:20000
reference_image_urlsarray
Opcional
URLs de imagens de referência públicas; imagens, clipes de vídeo e personagens compartilham um limite de sete unidades de referência.
Limite de itens:7
seedinteger
Opcional
Semente de geração determinística.
Intervalo:0 - 2147483647
video_listarray
Opcional
Clipes de vídeo de origem; cada clipe consome duas unidades de referência.
Limite de itens:1
video_list[].endsnumber
Obrigatório
Tempo de término do clipe em segundos; deve ser maior que o início e no máximo 10 segundos após o início.
Limite:0
video_list[].startnumber
Obrigatório
Tempo de início do clipe em segundos.
Limite:0
video_list[].urlstring
Obrigatório
URL de vídeo de origem pública.
Regras condicionais
Esses requisitos se aplicam quando todas as condições listadas corresponderem.
-
Quando
first_frame_image_url = {"present" => true},model = gemini-omni-flash-1-1- Obrigatório
- Não aceito
reference_image_urls,audio_ids,video_list,character_ids
-
Quando
last_frame_image_url = {"present" => true},model = gemini-omni-flash-1-1- Obrigatório
first_frame_image_url- Não aceito
-
Quando
model = gemini-omni-flash-preview- Obrigatório
- Não aceito
reference_image_urls,audio_ids,video_list,character_ids,first_frame_image_url,last_frame_image_url,duration_seconds,seed
-
Quando
model = gemini-omni-text-to-video- Obrigatório
- Não aceito
first_frame_image_url,last_frame_image_url
04
HTTP 202Criar aceitação
POST /api/v1/gemini_omni/text_to_video
Esquema de resposta
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
},
"task_replayed": {
"type": "boolean"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Exemplo de resposta
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}05
HTTP 200Consulta em processamento
GET /api/v1/gemini_omni/text_to_video/:id
Esquema de resposta
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Exemplo de resposta
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}06
HTTP 200Consulta concluída
GET /api/v1/gemini_omni/text_to_video/:id
Esquema de resposta
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"completed"
],
"type": "string"
},
"videos": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
}
},
"required": [
"id",
"status",
"videos",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Exemplo de resposta
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "completed",
"videos": [
{
"url": "https://file.runapi.ai/reference-video.mp4"
}
]
}07
HTTP 200Consulta falhou
GET /api/v1/gemini_omni/text_to_video/:id
Esquema de resposta
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Exemplo de resposta
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": "Task processing failed.",
"id": "tsk_reference_demo",
"status": "failed"
}08
HTTP 200Callback do cliente: concluído
POST callback_url
Esquema de resposta
JSON
{
"properties": {
"id": {
"type": "string"
},
"status": {
"enum": [
"completed"
],
"type": "string"
},
"videos": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
}
},
"required": [
"id",
"status",
"videos"
],
"type": "object",
"unevaluatedProperties": false
}Exemplo de resposta
JSON
{
"id": "tsk_reference_demo",
"status": "completed",
"videos": [
{
"url": "https://file.runapi.ai/reference-video.mp4"
}
]
}09
HTTP 200Callback do cliente: falhou
POST callback_url
Esquema de resposta
JSON
{
"properties": {
"error": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"code": {
"type": "string"
},
"limit_cents": {
"type": "integer"
},
"message": {
"type": "string"
},
"reset_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"used_cents": {
"type": "integer"
},
"window": {
"enum": [
"1h",
"1d",
"7d",
"daily",
"weekly",
"monthly",
"lifetime"
],
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
]
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error"
],
"type": "object",
"unevaluatedProperties": false
}Exemplo de resposta
JSON
{
"error": {
"code": "generation_failed",
"message": "Task processing failed."
},
"id": "tsk_reference_demo",
"status": "failed"
}10
HTTP 401Erros
POST /api/v1/gemini_omni/text_to_video
Esquema de resposta
JSON
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Exemplo de resposta
JSON
{
"error": "Authentication required"
}11
HTTP 401Erros
GET /api/v1/gemini_omni/text_to_video/:id
Esquema de resposta
JSON
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Exemplo de resposta
JSON
{
"error": "Authentication required"
}12
HTTP 400Erros
POST /api/v1/gemini_omni/text_to_video
Esquema de resposta
JSON
{
"oneOf": [
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
},
{
"properties": {
"error": {
"description": "Resumo de validação legível por humanos.",
"type": "string"
},
"errors": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "Mensagens de validação com chaves por campo de requisição público, com um array de strings legíveis por humanos para cada campo.",
"type": "object"
}
},
"required": [
"error",
"errors"
],
"type": "object",
"unevaluatedProperties": false
}
]
}Exemplo de resposta
JSON
{
"error": "model must be one of: gemini-omni-flash-1-1, gemini-omni-flash-preview, gemini-omni-text-to-video"
}13
HTTP 402Erros
POST /api/v1/gemini_omni/text_to_video
Esquema de resposta
JSON
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Exemplo de resposta
JSON
{
"error": "Insufficient balance"
}14
HTTP 429Erros
POST /api/v1/gemini_omni/text_to_video
Esquema de resposta
JSON
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Exemplo de resposta
JSON
{
"error": "API key credit limit exceeded"
}15
HTTP 409Erros
POST /api/v1/gemini_omni/text_to_video
Esquema de resposta
JSON
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Exemplo de resposta
JSON
{
"error": "The request uses features that are not supported for the selected model"
}16
HTTP 429Erros
POST /api/v1/gemini_omni/text_to_video
Esquema de resposta
JSON
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Exemplo de resposta
JSON
{
"error": "Rate limit reached. Please retry later."
}17
HTTP 503Erros
POST /api/v1/gemini_omni/text_to_video
Esquema de resposta
JSON
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Exemplo de resposta
JSON
{
"error": "Service under maintenance, please try again later"
}18
HTTP 504Erros
POST /api/v1/gemini_omni/text_to_video
Esquema de resposta
JSON
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Exemplo de resposta
JSON
{
"error": "The request timed out"
}19
HTTP 404Erros
GET /api/v1/gemini_omni/text_to_video/:id
Esquema de resposta
JSON
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Exemplo de resposta
JSON
{
"error": "Task with id 'tsk_reference_demo' not found"
}20
Exemplos de Código Gerados
Use cURL diretamente ou instale um SDK para a sua linguagem. Cada exemplo submete a requisição validada mostrada nesta referência.
Instalar
Shell
pip install runapi-gemini-omni
PYTHON
import os
from runapi.gemini_omni import GeminiOmniClient
client = GeminiOmniClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.text_to_video.create(
model="gemini-omni-text-to-video",
prompt="A presenter walks through a bright studio.",
duration_seconds=4
)