Como usar a API do Runway Gen-4.5? Crie seu primeiro vídeo em 5 minutos

TL;DR

• O Runway Gen-4.5 é o modelo de vídeo da Runway; no HiAPI há duas entradas, texto para vídeo e imagem para vídeo, abra a página do modelo e teste online; novos usuários ganham 200 créditos ao se cadastrar.
• As duas entradas custam $0.1715 por segundo: 5 segundos $0.8575, 8 segundos $1.372, 10 segundos $1.715.
• Como chamar: envie com POST /v1/tasks, consulte o resultado com taskId, o vídeo final fica em output[0].url.

O que o Runway Gen-4.5 faz

• Três durações: 5, 8 e 10 segundos: 8 segundos é o suficiente para um push-in, uma órbita ou uma subida lenta.
• 720p fixo: horizontal 1280×720, vertical 720×1280, sem escolher resolução.
• Imagem para vídeo tem 5 proporções: 16:9, 9:16, 4:3, 3:4, 1:1, a mesma imagem pode gerar versões para diferentes plataformas.
• O vídeo final não tem faixa de áudio: a imagem fica a cargo do modelo, o som é adicionado na edição.

She turns her head toward the camera and smiles, hair moves in a light breeze, slow push-in

Gerar com este prompt → (envie o primeiro frame de um retrato, escolha 5 segundos e 3:4)

runway-gen-4.5/image-to-video, 3:4, 832×1104, 5 segundos, $0.8575. Primeiro frame: .

Ela vira o rosto de perfil para a câmera e sorri, os fios de cabelo se movem levemente, a câmera avança até um close no rosto. O prompt descreve apenas a ação e o movimento de câmera; a aparência da pessoa e a luz da janela vêm do primeiro frame.

Como escolher entre as duas entradas

ID do modelo	Entrada	Duração	Proporção	Indicado para
runway-gen-4.5/text-to-video	prompt	5 / 8 / 10 segundos (9:16 apenas 5 / 10)	16:9, 9:16	Sem material, começar pelo texto
runway-gen-4.5/image-to-video	1 primeiro frame + prompt	5 / 8 / 10 segundos	16:9, 9:16, 4:3, 3:4, 1:1	O sujeito precisa ser igual ao da imagem original, ou precisa de quadrado, 4:3, 3:4

As duas entradas têm o mesmo preço, $0.1715 por segundo.

Dois caminhos para começar

Testar no navegador (3 passos)

1. Abra a página do modelo texto para vídeo ou imagem para vídeo e faça login.
2. Escreva o prompt; em imagem para vídeo, envie primeiro um frame inicial.
3. Escolha 5 segundos e a proporção, clique em executar.

Chamar pela API (3 passos)

1. Crie a chave na página API Key do console e coloque na variável de ambiente HIAPI_KEY.
2. Envie com POST https://api.hiapi.ai/v1/tasks, retorna data.taskId.
3. Consulte com GET /v1/tasks/{taskId} até status ser success, baixe output[0].url.

curl: primeiro vídeo

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "runway-gen-4.5/text-to-video",
    "input": {
      "prompt": "A lone stone lighthouse on a rugged sea cliff at dusk, heavy waves crashing against the rocks, the lamp beam sweeping across dark storm clouds, slow cinematic push-in, drifting sea mist, dramatic lighting",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }'

5 segundos, 16:9, $0.8575. O vídeo final fica assim:

A lone stone lighthouse on a rugged sea cliff at dusk, heavy waves crashing against the rocks, the lamp beam sweeping across dark storm clouds, slow cinematic push-in, drifting sea mist, dramatic lighting

Gerar com este prompt → (escolha 5 segundos, 16:9)

runway-gen-4.5/text-to-video, 16:9, 1280×720, 5 segundos, $0.8575.

Python: enviar, consultar, baixar

# pip install requests; antes execute export HIAPI_KEY=sua Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(model, timeout_s=900, **inp):
    # Ao repetir a mesma tarefa, use o mesmo Idempotency-Key para evitar cobrança duplicada
    r = requests.post(API, json={"model": model, "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

# Imagem para vídeo: a mesma imagem em versão 1:1, 8 segundos ($1.372)
url = generate(
    "runway-gen-4.5/image-to-video",
    prompt="The scene slowly comes alive: clouds drift, light shifts across the mountain lake, gentle forward camera move",
    image_urls=["https://seu-hospedagem-de-imagem/lake.jpg"],
    duration=8, aspect_ratio="1:1",
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

Tabela de parâmetros

Campo	Obrigatório	Valores	Descrição
prompt	Sim	1–1000 caracteres	Descreva o sujeito, a ação e o enquadramento; em imagem para vídeo, descreva só a ação e o enquadramento
duration	Não	5 (padrão) / 8 / 10	Texto para vídeo em 9:16 só aceita 5 / 10
aspect_ratio	Não	Texto: 16:9 (padrão) 9:16; imagem: 16:9 (padrão) 9:16 4:3 3:4 1:1	Em imagem para vídeo, o primeiro frame é cortado ao centro conforme a proporção
image_urls	Obrigatório em imagem para vídeo	Apenas 1, jpeg/png/webp, ≤10MB	Primeiro frame; texto para vídeo não aceita este campo

Não há resolution, seed, negative_prompt, nem frame final.

Erros que você vai encontrar

Se os parâmetros estiverem errados no envio, a API retorna 400 direto, sem criar tarefa nem cobrar:

• duration: value must be one of 5, 10: texto para vídeo escolheu 9:16 e enviou 8 segundos.
• duration: value must be one of 5, 8, 10: a duração tem apenas essas três opções.
• image_urls: maxItems: got 2, want 1: imagem para vídeo aceita apenas um frame inicial, não suporta frame final.
• image_urls: missing required field "image_urls": imagem para vídeo não enviou o frame inicial.
• prompt: maxLength: got 3,000, want 1,000: o prompt tem no máximo 1000 caracteres.
• additional properties 'negative_prompt', 'cfg_scale' not allowed: esses dois campos não existem no Runway Gen-4.5.

Atenção antes de ir para produção

• Use callback em vez de polling: adicione "callback": {"url": "https://seu-dominio/hiapi/callback"} no nível superior da requisição (mesmo nível de input) e deduplique por taskId.
• Transfira logo: output[0].url expira em cerca de 7 dias, salve no seu próprio armazenamento assim que receber.
• Escreva duration e aspect_ratio explicitamente: texto para vídeo em vertical deve evitar 8 segundos, fixar no código é o mais seguro.
• Retentativas com chave de idempotência: adicione Idempotency-Key no cabeçalho da requisição, a mesma chave cria a tarefa apenas uma vez.

Perguntas frequentes

Dá para gerar em 1080p ou 4K?

Não, a saída é fixa em 720p. Para 1080p, use o Kling 2.5 Turbo; veja a comparação em Comparação entre Runway Gen-4.5 e Kling 2.5 Turbo.

O vídeo final tem som?

Não, a saída tem apenas imagem. Trilha sonora, efeitos e narração são adicionados na edição.

Imagem para vídeo aceita frame final?

Não, image_urls aceita apenas uma imagem. Para controlar o final com frame final, use imagem para vídeo do Kling 2.5 Turbo.

O que acontece se a proporção do primeiro frame for diferente da proporção escolhida?

O primeiro frame é cortado ao centro conforme a proporção escolhida; colocar o sujeito no centro é o mais seguro.

Para detalhes de preço, veja Preço da API do Runway Gen-4.5; para mais cenários, veja Guia completo de prompts do Runway Gen-4.5. Para ver o resultado primeiro, copie o prompt do farol acima e gere o primeiro na página do modelo.