Was macht Runway ML API?
Übersicht
Das Gen-3 Alpha Turbo Modell von Runway generiert hochwertige Videos aus Textaufforderungen oder Bildern. Die REST API folgt einem asynchronen Task-Muster: einen Task erstellen, auf Fertigstellung warten und dann das Ergebnis herunterladen. Verwenden Sie es, um kinematografische Clips zu produzieren, Bilder zu animieren oder automatisierte Video-Content-Pipelines aufzubauen.
Einrichtung
pip install requests python-dotenv
export RUNWAY_API_KEY="your_api_key_here"
Basis-URL: https://api.dev.runwayml.com/v1
API-Dokumentation: https://docs.runwayml.com
Kernkonzepte
- Task: Ein asynchroner Videogenerierungsauftrag. Gibt sofort eine
task_idzurück. - Gen-3 Alpha Turbo: Schnellstes Gen-3 Modell – am besten für Produktionspipelines geeignet.
- Bild-zu-Video (
gen3a_turbo): Ein Standbild in Bewegung versetzen. - Text-zu-Video: Video ausschließlich aus einer Textaufforderung generieren.
- Dauer: 5 oder 10 Sekunden.
- Seitenverhältnis:
1280:720(Querformat),720:1280(Hochformat),1104:832,832:1104,960:960(Quadrat).
Anleitung
Schritt 1: Client einrichten
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"
}
Schritt 2: Text-zu-Video-Generierung
def text_to_video(
prompt_text: str,
duration: int = 5,
ratio: str = "1280:720",
seed: int = None
) -> str:
"""Sendet einen Text-zu-Video-Task ab und gibt die task_id zurück."""
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="Eine Drohnenaufnahme über einem nebligen Bergtal zur goldenen Stunde, kinematografisch, Zeitlupe",
duration=5,
ratio="1280:720"
)
print(f"Task übermittelt: {task_id}")
Schritt 3: Bild-zu-Video-Generierung
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:
"""Animiert ein Bild in ein Video. image_path kann ein lokaler Pfad oder eine URL sein."""
if image_path.startswith("http"):
prompt_image = image_path
else:
# Lokale Datei als data URI codieren
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="produktaufnahme.png",
prompt_text="Das Produkt dreht sich langsam, funkelnde Partikel schweben darum herum, luxuriöses Gefühl",
duration=5,
ratio="1280:720"
)
print(f"Task übermittelt: {task_id}")
Schritt 4: Task-Status abfragen
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]:
"""Wartet, bis der Task abgeschlossen ist; gibt eine Liste der Video-URLs zurück."""
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"] # Liste der Video-URLs
elif status in ("FAILED", "CANCELLED"):
raise RuntimeError(f"Task {status}: {task.get('failure', '')}")
elif time.time() - start > timeout:
raise TimeoutError(f"Task nach {timeout}s nicht abgeschlossen")
time.sleep(poll_interval)
output_urls = wait_for_task(task_id)
print(f"Video(s) bereit: {output_urls}")
Schritt 5: Ergebnis herunterladen
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"Gespeichert: {output_path} ({size_mb:.1f} MB)")
return output_path
download_video(output_urls[0], "nebeltal.mp4")
Vollständiges Pipeline-Beispiel
def generate_and_download(prompt: str, output_path: str = "output.mp4", **kwargs) -> str:
"""Ein-Schritt: Video aus Text generieren und herunterladen."""
print(f"Generiere: {prompt[:80]}...")
task_id = text_to_video(prompt, **kwargs)
urls = wait_for_task(task_id)
return download_video(urls[0], output_path)
# Einen Produktwerbeclip generieren
generate_and_download(
prompt="Nahaufnahme eines eleganten Smartphones auf einem weißen Tisch, Bildschirm leuchtet auf, sanfte Kamera-Rückwärtsbewegung",
output_path="produktwerbung.mp4",
duration=5,
ratio="1280:720"
)
Parameter-Referenz
| Parameter | Werte | Beschreibung |
|---|---|---|
model | gen3a_turbo | Gen-3 Alpha Turbo verwenden (schnellstes) |
duration | 5, 10 | Videolänge in Sekunden |
ratio | 1280:720, 720:1280, 1104:832, 832:1104, 960:960 | Seitenverhältnis der Auflösung |
seed | Ganzzahl | Reproduzierbarkeits-Seed für deterministische Ausgaben |
promptText | Zeichenkette | Textaufforderung, die das gewünschte Video beschreibt |
promptImage | URL oder data URI | Ausgangsbild für Bild-zu-Video |
Richtlinien
- Runway-Aufgaben dauern je nach Länge und Auslastung 30–120 Sekunden.
- Ausgabe-URLs verfallen nach einer gewissen Zeit – laden Sie Videos nach der Generierung umgehend herunter.
- Halten Sie Aufforderungen beschreibend und kinematografisch: Kamera-Bewegung, Beleuchtung, Stimmung angeben.
- Verwenden Sie
seed, um beim Iterieren über Aufforderungen das gleiche Ergebnis zu reproduzieren. - Für die Stapelgenerierung: Tasks parallel in die Warteschlange stellen, aber Ratenlimits beachten (HTTP 429 prüfen und nach dem
Retry-AfterHeader-Wert wiederholen). - API-Schlüssel in Umgebungsvariablen speichern – niemals hartcodieren.
- Unter https://docs.runwayml.com finden Sie die aktuellen Modellnamen und Endpunkte, da diese sich schnell weiterentwickeln.