¿Qué hace API de Runway ML?
Resumen
El modelo Gen-3 Alpha Turbo de Runway genera video de alta calidad a partir de indicaciones de texto o imágenes. La API REST sigue un patrón de tareas asíncronas: crear una tarea, consultar hasta que finalice y luego descargar el resultado. Úsalo para producir clips cinematográficos, animar imágenes o construir pipelines automatizados de contenido de video.
Configuración
pip install requests python-dotenv
export RUNWAY_API_KEY="tu_clave_api_aqui"
URL base: https://api.dev.runwayml.com/v1
Documentación de la API: https://docs.runwayml.com
Conceptos clave
- Tarea: Un trabajo de generación de video asíncrono. Devuelve inmediatamente un
task_id. - Gen-3 Alpha Turbo: El modelo Gen-3 más rápido, ideal para pipelines de producción.
- imagen-a-video (
gen3a_turbo): Animar una imagen fija para crear movimiento. - texto-a-video: Generar video únicamente a partir de un prompt de texto.
- Duración: 5 o 10 segundos.
- Relación de aspecto:
1280:720(apaisado),720:1280(retrato),1104:832,832:1104,960:960(cuadrado).
Instrucciones
Paso 1: Configurar el 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"
}
Paso 2: Generación de texto a video
def text_to_video(
prompt_text: str,
duration: int = 5,
ratio: str = "1280:720",
seed: int = None
) -> str:
"""Envía una tarea de texto a video y devuelve el 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="Un dron volando sobre un valle montañoso brumoso durante la hora dorada, cinematográfico, cámara lenta",
duration=5,
ratio="1280:720"
)
print(f"Tarea enviada: {task_id}")
Paso 3: Generación de imagen a video
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 una imagen para convertirla en video. image_path puede ser un archivo local o una URL."""
if image_path.startswith("http"):
prompt_image = image_path
else:
# Codificar archivo 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="product_shot.png",
prompt_text="El producto gira lentamente, partículas brillantes flotan a su alrededor, sensación de lujo",
duration=5,
ratio="1280:720"
)
print(f"Tarea enviada: {task_id}")
Paso 4: Consultar el estado de la tarea
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]:
"""Consulta hasta que la tarea se complete; devuelve una lista de URLs de video de salida."""
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] Estado: {status} ({int(progress*100)}%)")
if status == "SUCCEEDED":
return task["output"] # lista de URLs de video
elif status in ("FAILED", "CANCELLED"):
raise RuntimeError(f"Tarea {status}: {task.get('failure', '')}")
elif time.time() - start > timeout:
raise TimeoutError(f"La tarea no ha finalizado después de {timeout}s")
time.sleep(poll_interval)
output_urls = wait_for_task(task_id)
print(f"Video(s) listo(s): {output_urls}")
Paso 5: Descargar el 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"Guardado: {output_path} ({size_mb:.1f} MB)")
return output_path
download_video(output_urls[0], "mountain_valley.mp4")
Ejemplo de pipeline completo
def generate_and_download(prompt: str, output_path: str = "output.mp4", **kwargs) -> str:
"""Un solo paso: generar video desde texto y descargarlo."""
print(f"Generando: {prompt[:80]}...")
task_id = text_to_video(prompt, **kwargs)
urls = wait_for_task(task_id)
return download_video(urls[0], output_path)
# Generar un clip de anuncio de producto
generate_and_download(
prompt="Primer plano de un teléfono inteligente elegante sobre un escritorio blanco, la pantalla se ilumina, suave alejamiento de cámara",
output_path="product_ad.mp4",
duration=5,
ratio="1280:720"
)
Referencia de parámetros
| Parámetro | Valores | Descripción |
|---|---|---|
model | gen3a_turbo | Usa Gen-3 Alpha Turbo (el más rápido) |
duration | 5, 10 | Duración del video en segundos |
ratio | 1280:720, 720:1280, 1104:832, 832:1104, 960:960 | Relación de aspecto de resolución |
seed | entero | Semilla de reproducibilidad para salidas deterministas |
promptText | cadena | Prompt de texto que describe el video deseado |
promptImage | URL o data URI | Imagen de inicio para imagen a video |
Directrices
- Las tareas de Runway tardan entre 30 y 120 segundos dependiendo de la duración y la carga.
- Las URLs de salida caducan después de un tiempo; descarga los videos inmediatamente después de la generación.
- Mantén los prompts descriptivos y cinematográficos: incluye movimiento de cámara, iluminación, ambiente.
- Usa
seedpara reproducir el mismo resultado al iterar sobre prompts. - Para generación por lotes, encola las tareas en paralelo pero respeta los límites de velocidad (verifica HTTP 429 y reintenta después del valor del encabezado
Retry-After). - Almacena las claves API en variables de entorno, nunca las codifiques en el código.
- Consulta https://docs.runwayml.com para ver los nombres y endpoints de modelos más recientes, ya que evolucionan rápidamente.