O que API Runway ML faz?
Visão Geral
O modelo Gen-3 Alpha Turbo da Runway gera vídeos de alta qualidade a partir de prompts de texto ou imagens. A API REST segue um padrão de tarefa assíncrona: crie uma tarefa, monitore a conclusão e baixe o resultado. Use-a para produzir clipes cinematográficos, animar imagens ou construir pipelines automatizados de conteúdo de vídeo.
Configuração
pip install requests python-dotenv
export RUNWAY_API_KEY="sua_chave_api_aqui"
URL base: https://api.dev.runwayml.com/v1
Documentação da API: https://docs.runwayml.com
Conceitos Principais
- Tarefa: Um job assíncrono de geração de vídeo. Retorna um
task_idimediatamente. - Gen-3 Alpha Turbo: O modelo Gen-3 mais rápido — ideal para pipelines de produção.
- imagem-para-vídeo (
gen3a_turbo): Anime uma imagem estática. - texto-para-vídeo: Gere vídeo puramente a partir de um prompt de texto.
- Duração: 5 ou 10 segundos.
- Proporção:
1280:720(paisagem),720:1280(retrato),1104:832,832:1104,960:960(quadrado).
Instruções
Passo 1: Configurar o cliente
import os
import time
import requests
API_KEY = os.environ["RUNWAY_API_KEY"]
BASE_URL = "https://api.dev.runwayml.com/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
"X-Runway-Version": "2024-11-06"
}
Passo 2: Geração de texto para vídeo
def text_to_video(
prompt_text: str,
duration: int = 5,
ratio: str = "1280:720",
seed: int = None
) -> str:
"""Envia uma tarefa de texto para vídeo e retorna o task_id."""
payload = {
"model": "gen3a_turbo",
"promptText": prompt_text,
"duration": duration,
"ratio": ratio
}
if seed is not None:
payload["seed"] = seed
r = requests.post(f"{BASE_URL}/image_to_video", json=payload, headers=HEADERS)
r.raise_for_status()
return r.json()["id"]
task_id = text_to_video(
prompt_text="Um plano aéreo sobrevoando um vale montanhoso com névoa na hora dourada, cinematográfico, câmera lenta",
duration=5,
ratio="1280:720"
)
print(f"Tarefa enviada: {task_id}")
Passo 3: Geração de imagem para vídeo
import base64
from pathlib import Path
def image_to_video(
image_path: str,
prompt_text: str = "",
duration: int = 5,
ratio: str = "1280:720",
seed: int = None
) -> str:
"""Anima uma imagem para vídeo. image_path pode ser um arquivo local ou URL."""
if image_path.startswith("http"):
prompt_image = image_path
else:
# Codifica arquivo local como data URI
img_bytes = Path(image_path).read_bytes()
ext = Path(image_path).suffix.lstrip(".").lower()
mime = {"jpg": "image/jpeg", "jpeg": "image/jpeg", "png": "image/png", "webp": "image/webp"}.get(ext, "image/png")
b64 = base64.b64encode(img_bytes).decode()
prompt_image = f"data:{mime};base64,{b64}"
payload = {
"model": "gen3a_turbo",
"promptImage": prompt_image,
"promptText": prompt_text,
"duration": duration,
"ratio": ratio
}
if seed is not None:
payload["seed"] = seed
r = requests.post(f"{BASE_URL}/image_to_video", json=payload, headers=HEADERS)
r.raise_for_status()
return r.json()["id"]
task_id = image_to_video(
image_path="foto_produto.png",
prompt_text="O produto gira lentamente, partículas brilhantes flutuam ao redor, sensação de luxo",
duration=5,
ratio="1280:720"
)
print(f"Tarefa enviada: {task_id}")
Passo 4: Monitorar o status da tarefa
def get_task(task_id: str) -> dict:
r = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS)
r.raise_for_status()
return r.json()
def wait_for_task(task_id: str, poll_interval: int = 5, timeout: int = 600) -> list[str]:
"""Monitora até a tarefa ser concluída; retorna lista de URLs de vídeo de saída."""
start = time.time()
while True:
task = get_task(task_id)
status = task["status"]
progress = task.get("progress", 0)
print(f"[{int(time.time()-start)}s] Status: {status} ({int(progress*100)}%)")
if status == "SUCCEEDED":
return task["output"] # lista de URLs de vídeo
elif status in ("FAILED", "CANCELLED"):
raise RuntimeError(f"Tarefa {status}: {task.get('failure', '')}")
elif time.time() - start > timeout:
raise TimeoutError(f"Tarefa não concluída após {timeout}s")
time.sleep(poll_interval)
output_urls = wait_for_task(task_id)
print(f"Vídeo(s) pronto(s): {output_urls}")
Passo 5: Baixar o resultado
def download_video(url: str, output_path: str = "output.mp4") -> str:
r = requests.get(url, stream=True)
r.raise_for_status()
with open(output_path, "wb") as f:
for chunk in r.iter_content(chunk_size=8192):
f.write(chunk)
size_mb = os.path.getsize(output_path) / 1024 / 1024
print(f"Salvo: {output_path} ({size_mb:.1f} MB)")
return output_path
download_video(output_urls[0], "vale_montanhoso.mp4")
Exemplo de pipeline completo
def generate_and_download(prompt: str, output_path: str = "output.mp4", **kwargs) -> str:
"""Única chamada: gera vídeo a partir de texto e baixa."""
print(f"Gerando: {prompt[:80]}...")
task_id = text_to_video(prompt, **kwargs)
urls = wait_for_task(task_id)
return download_video(urls[0], output_path)
# Gere um clipe de anúncio de produto
generate_and_download(
prompt="Close-up de um smartphone elegante sobre uma mesa branca, tela acende, suave afastamento de câmera",
output_path="anuncio_produto.mp4",
duration=5,
ratio="1280:720"
)
Referência de parâmetros
| Parâmetro | Valores | Descrição |
|---|---|---|
model | gen3a_turbo | Use Gen-3 Alpha Turbo (mais rápido) |
duration | 5, 10 | Duração do vídeo em segundos |
ratio | 1280:720, 720:1280, 1104:832, 832:1104, 960:960 | Proporção de resolução |
seed | inteiro | Semente de reprodutibilidade para resultados determinísticos |
promptText | string | Prompt de texto descrevendo o vídeo desejado |
promptImage | URL ou data URI | Imagem inicial para imagem-para-vídeo |
Diretrizes
- Tarefas do Runway levam de 30 a 120 segundos, dependendo da duração e carga.
- As URLs de saída expiram após um período — baixe os vídeos imediatamente após a geração.
- Mantenha os prompts descritivos e cinematográficos: inclua movimento de câmera, iluminação e clima.
- Use
seedpara reproduzir o mesmo resultado ao iterar sobre prompts. - Para geração em lote, enfileire tarefas em paralelo, mas respeite os limites de taxa (verifique HTTP 429 e repita após o valor do cabeçalho
Retry-After). - Armazene chaves de API em variáveis de ambiente — nunca as codifique diretamente.
- Consulte https://docs.runwayml.com para obter os nomes e endpoints mais recentes do modelo, pois eles evoluem rapidamente.