Geração de Vídeo (Multi-Gateway)
Gere vídeos de IA a partir de prompts de texto. Suporta vários provedores através de dois gateways de API:
| Gateway | Variável de Ambiente | Provedores | Ferramenta |
|---|---|---|---|
| fal.ai | FAL_KEY | Seedance 2.0 (padrão + rápido), Kling v3/v2.1, MiniMax, VEO | seedance_video, kling_video, minimax_video, veo_video |
| HeyGen | HEYGEN_API_KEY | VEO 3.1, Kling Pro, Sora v2, Runway Gen-4, Seedance Pro / Lite (1.x) | heygen_video |
Padrão premium preferido — Seedance 2.0. Quando qualquer gateway premium estiver configurado (FAL_KEY → seedance_video, ou o caminho de Video Agent / Avatar Shots do HeyGen), o Seedance 2.0 é o padrão preferido para trabalhos cinematográficos, de trailer e clipes de alta fidelidade. É o único modelo na frota com áudio sincronizado nativo em uma única passagem, geração de múltiplas tomadas, controle de câmera de nível de diretor e sincronização labial a partir de diálogo citado, e ocupa o primeiro lugar no Artificial Analysis Elo no início de 2026. Mude para outro modelo apenas quando o usuário tiver um motivo específico (orçamento, preferência de provedor, ajuste estilístico como VEO para paisagens fotorrealistas ou Kling para um visual anime específico). Consulte a Camada 3 seedance-2-0 para o guia autoritativo de prompting e parâmetros.
IMPORTANTE: Sempre use video_selector em vez de chamar as ferramentas do provedor diretamente. O seletor lida com verificações de disponibilidade, comparação de custos e fallback automático, e seu mecanismo de pontuação já tende para o Seedance 2.0 para intenção cinematográfica.
Autenticação
Use o gateway configurado que melhor corresponda aos provedores disponíveis e aos objetivos de custo/qualidade do usuário.
- HeyGen: Defina
HEYGEN_API_KEYpara acessar o gateway multi-modelo. - fal.ai: Defina
FAL_KEYpara acessar Kling, MiniMax e Veo através do fal.ai.
Não descreva nenhum dos gateways como padrão ou melhor escolha sem antes verificar o registro e a adequação à tarefa atual.
curl -X POST "https://api.heygen.com/v1/workflows/executions" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"workflow_type": "GenerateVideoNode", "input": {"prompt": "Uma tomada de drone sobrevoando uma cidade costeira ao pôr do sol"}}'
Fluxo de Trabalho Padrão
- Chame
POST /v1/workflows/executionscomworkflow_type: "GenerateVideoNode"e seu prompt - Receba um
execution_idna resposta - Faça polling de
GET /v1/workflows/executions/{id}a cada 10 segundos até o status sercompleted - Use o
video_urlretornado na saída
Executar Geração de Vídeo
Endpoint
POST https://api.heygen.com/v1/workflows/executions
Campos da Requisição
| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
workflow_type | string | S | Deve ser "GenerateVideoNode" |
input.prompt | string | S | Descrição textual do vídeo a ser gerado |
input.provider | string | Provedor de geração de vídeo (padrão: "veo_3_1"). Veja Provedores abaixo. | |
input.aspect_ratio | string | Proporção de aspecto (padrão: "16:9"). Valores comuns: "16:9", "9:16", "1:1" | |
input.reference_image_url | string | URL da imagem de referência para geração de imagem para vídeo | |
input.tail_image_url | string | URL da imagem final para orientação do último quadro | |
input.config | object | Substituições de configuração específicas do provedor |
Provedores
| Provedor | Valor | Descrição |
|---|---|---|
| VEO 3.1 | "veo_3_1" | Google VEO 3.1 (padrão, maior qualidade) |
| VEO 3.1 Fast | "veo_3_1_fast" | Variante mais rápida do VEO 3.1 |
| VEO 3 | "veo3" | Google VEO 3 |
| VEO 3 Fast | "veo3_fast" | Variante mais rápida do VEO 3 |
| VEO 2 | "veo2" | Google VEO 2 |
| Kling Pro | "kling_pro" | Modelo Kling Pro |
| Kling V2 | "kling_v2" | Modelo Kling V2 |
| Sora V2 | "sora_v2" | OpenAI Sora V2 |
| Sora V2 Pro | "sora_v2_pro" | OpenAI Sora V2 Pro |
| Runway Gen-4 | "runway_gen4" | Runway Gen-4 |
| Seedance Lite | "seedance_lite" | Seedance Lite |
| Seedance Pro | "seedance_pro" | Seedance Pro |
| LTX Distilled | "ltx_distilled" | LTX Distilled (mais rápido) |
curl
curl -X POST "https://api.heygen.com/v1/workflows/executions" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Uma tomada de drone sobrevoando uma cidade costeira na hora dourada, iluminação cinematográfica",
"provider": "veo_3_1",
"aspect_ratio": "16:9"
}
}'
TypeScript
interface GenerateVideoInput {
prompt: string;
provider?: string;
aspect_ratio?: string;
reference_image_url?: string;
tail_image_url?: string;
config?: Record<string, any>;
}
interface ExecuteResponse {
data: {
execution_id: string;
status: "submitted";
};
}
async function generateVideo(input: GenerateVideoInput): Promise<string> {
const response = await fetch("https://api.heygen.com/v1/workflows/executions", {
method: "POST",
headers: {
"X-Api-Key": process.env.HEYGEN_API_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify({
workflow_type: "GenerateVideoNode",
input,
}),
});
const json: ExecuteResponse = await response.json();
return json.data.execution_id;
}
Python
import requests
import os
def generate_video(
prompt: str,
provider: str = "veo_3_1",
aspect_ratio: str = "16:9",
reference_image_url: str | None = None,
tail_image_url: str | None = None,
) -> str:
payload = {
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": prompt,
"provider": provider,
"aspect_ratio": aspect_ratio,
},
}
if reference_image_url:
payload["input"]["reference_image_url"] = reference_image_url
if tail_image_url:
payload["input"]["tail_image_url"] = tail_image_url
response = requests.post(
"https://api.heygen.com/v1/workflows/executions",
headers={
"X-Api-Key": os.environ["HEYGEN_API_KEY"],
"Content-Type": "application/json",
},
json=payload,
)
data = response.json()
return data["data"]["execution_id"]
Formato da Resposta
{
"data": {
"execution_id": "node-gw-v1d2e3o4",
"status": "submitted"
}
}
Verificar Status
Endpoint
GET https://api.heygen.com/v1/workflows/executions/{execution_id}
curl
curl -X GET "https://api.heygen.com/v1/workflows/executions/node-gw-v1d2e3o4" \
-H "X-Api-Key: $HEYGEN_API_KEY"
Formato da Resposta (Concluído)
{
"data": {
"execution_id": "node-gw-v1d2e3o4",
"status": "completed",
"output": {
"video": {
"video_url": "https://resource.heygen.ai/generated/video.mp4",
"video_id": "abc123"
},
"asset_id": "asset-xyz789"
}
}
}
Polling para Conclusão
async function generateVideoAndWait(
input: GenerateVideoInput,
maxWaitMs = 600000,
pollIntervalMs = 10000
): Promise<{ video_url: string; video_id: string; asset_id: string }> {
const executionId = await generateVideo(input);
console.log(`Geração de vídeo submetida: ${executionId}`);
const startTime = Date.now();
while (Date.now() - startTime < maxWaitMs) {
const response = await fetch(
`https://api.heygen.com/v1/workflows/executions/${executionId}`,
{ headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! } }
);
const { data } = await response.json();
switch (data.status) {
case "completed":
return {
video_url: data.output.video.video_url,
video_id: data.output.video.video_id,
asset_id: data.output.asset_id,
};
case "failed":
throw new Error(data.error?.message || "Falha na geração do vídeo");
case "not_found":
throw new Error("Fluxo de trabalho não encontrado");
default:
await new Promise((r) => setTimeout(r, pollIntervalMs));
}
}
throw new Error("Tempo limite da geração de vídeo excedido");
}
Exemplos de Uso
Texto para Vídeo Simples
curl -X POST "https://api.heygen.com/v1/workflows/executions" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Uma pessoa caminhando por um parque ensolarado, profundidade de campo rasa"
}
}'
Imagem para Vídeo
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Anime esta foto de produto com um zoom lento e efeitos de partículas suaves",
"reference_image_url": "https://exemplo.com/foto-produto.png",
"provider": "kling_pro"
}
}
Formato Vertical para Redes Sociais
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Interior de uma cafeteria moderna, câmera deslizando lentamente pelo balcão",
"aspect_ratio": "9:16",
"provider": "veo_3_1"
}
}
Geração Rápida com LTX
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Formas coloridas abstratas se transformando e fluindo",
"provider": "ltx_distilled"
}
}
Melhores Práticas
- Seja descritivo nos prompts — inclua detalhes de movimento de câmera, iluminação, estilo e clima
- Padrão para Seedance 2.0 (via
seedance_video) para trabalhos cinematográficos e com movimento quandoFAL_KEYestiver configurado — áudio sincronizado em uma única passagem, múltiplas tomadas, sincronização labial, câmera de nível de diretor. Use VEO 3.1 / Sora V2 Pro quando o usuário quiser especificamente personagens em movimento do Google ou OpenAI; useltx_distilledouveo3_fastapenas quando a velocidade for a restrição crítica - Use imagens de referência para geração de imagem para vídeo — ótimo para animar fotos de produtos ou imagens estáticas
- A geração de vídeo é o fluxo de trabalho mais lento — aguarde até 5 minutos, faça polling a cada 10 segundos
- A proporção de aspecto é importante — use
9:16para stories/reels de redes sociais,16:9para paisagem,1:1para quadrado - A saída inclui
asset_id— use para referenciar o vídeo gerado em outros fluxos de trabalho do HeyGen - As URLs de saída são temporárias — baixe ou salve os vídeos gerados imediatamente