API Runway ML
Présentation
Le modèle Gen-3 Alpha Turbo de Runway génère des vidéos de haute qualité à partir de prompts textuels ou d'images. L'API REST suit un modèle de tâche asynchrone : créez une tâche, interrogez son état d'avancement, puis téléchargez le résultat. Utilisez-la pour produire des clips cinématographiques, animer des images ou créer des pipelines automatisés de contenu vidéo.
Configuration
pip install requests python-dotenv
export RUNWAY_API_KEY="votre_clé_api_ici"
URL de base : https://api.dev.runwayml.com/v1
Documentation API : https://docs.runwayml.com
Concepts clés
- Tâche : Un travail de génération vidéo asynchrone. Renvoie immédiatement un
task_id. - Gen-3 Alpha Turbo : Le modèle Gen-3 le plus rapide — idéal pour les pipelines de production.
- Image-vers-vidéo (
gen3a_turbo) : Anime une image fixe pour créer du mouvement. - Texte-vers-vidéo : Génère une vidéo uniquement à partir d'un prompt textuel.
- Durée : 5 ou 10 secondes.
- Ratio :
1280:720(paysage),720:1280(portrait),1104:832,832:1104,960:960(carré).
Instructions
Étape 1 : Configurer le client
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"
}
Étape 2 : Génération texte-vers-vidéo
def text_to_video(
prompt_text: str,
duration: int = 5,
ratio: str = "1280:720",
seed: int = None
) -> str:
"""Soumet une tâche texte-vers-vidéo et renvoie le 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 plan de drone survolant une vallée de montagne brumeuse à l'heure dorée, cinématographique, ralenti",
duration=5,
ratio="1280:720"
)
print(f"Tâche soumise : {task_id}")
Étape 3 : Génération image-vers-vidéo
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:
"""Anime une image en vidéo. image_path peut être un fichier local ou une URL."""
if image_path.startswith("http"):
prompt_image = image_path
else:
# Encode le fichier local en URI de données
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="Le produit tourne lentement, des particules scintillantes flottent autour, sensation de luxe",
duration=5,
ratio="1280:720"
)
print(f"Tâche soumise : {task_id}")
Étape 4 : Interroger l'état de la tâche
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]:
"""Interroge jusqu'à ce que la tâche se termine ; renvoie la liste des URL des vidéos de sortie."""
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] Statut : {status} ({int(progress*100)}%)")
if status == "SUCCEEDED":
return task["output"] # liste d'URL de vidéos
elif status in ("FAILED", "CANCELLED"):
raise RuntimeError(f"Tâche {status} : {task.get('failure', '')}")
elif time.time() - start > timeout:
raise TimeoutError(f"Tâche pas terminée après {timeout}s")
time.sleep(poll_interval)
output_urls = wait_for_task(task_id)
print(f"Vidéo(s) prête(s) : {output_urls}")
Étape 5 : Télécharger le résultat
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"Enregistré : {output_path} ({size_mb:.1f} Mo)")
return output_path
download_video(output_urls[0], "mountain_valley.mp4")
Exemple de pipeline complet
def generate_and_download(prompt: str, output_path: str = "output.mp4", **kwargs) -> str:
"""En une seule étape : génère une vidéo à partir de texte et la télécharge."""
print(f"Génération : {prompt[:80]}...")
task_id = text_to_video(prompt, **kwargs)
urls = wait_for_task(task_id)
return download_video(urls[0], output_path)
# Générer un clip publicitaire pour un produit
generate_and_download(
prompt="Gros plan d'un smartphone élégant sur un bureau blanc, l'écran s'allume, zoom arrière fluide",
output_path="product_ad.mp4",
duration=5,
ratio="1280:720"
)
Référence des paramètres
| Paramètre | Valeurs | Description |
|---|---|---|
model | gen3a_turbo | Utiliser Gen-3 Alpha Turbo (le plus rapide) |
duration | 5, 10 | Durée de la vidéo en secondes |
ratio | 1280:720, 720:1280, 1104:832, 832:1104, 960:960 | Ratio d'aspect de la résolution |
seed | entier | Graine de reproductibilité pour des sorties déterministes |
promptText | chaîne | Prompt textuel décrivant la vidéo souhaitée |
promptImage | URL ou URI de données | Image de départ pour l'image-vers-vidéo |
Recommandations
- Les tâches Runway prennent 30 à 120 secondes selon la durée et la charge.
- Les URL de sortie expirent après un certain temps — téléchargez les vidéos rapidement après la génération.
- Rédigez des prompts descriptifs et cinématographiques : incluez le mouvement de la caméra, l'éclairage, l'ambiance.
- Utilisez
seedpour reproduire le même résultat lorsque vous itérez sur des prompts. - Pour la génération par lots, mettez les tâches en file d'attente en parallèle mais respectez les limites de débit (vérifiez les codes HTTP 429 et réessayez après la valeur de l'en-tête
Retry-After). - Stockez les clés API dans des variables d'environnement — ne les codez jamais en dur.
- Consultez https://docs.runwayml.com pour connaître les derniers noms de modèles et points d'accès, car ils évoluent rapidement.