Référence API Runway Public

PRÉREQUIS : Exécutez d'abord +rw-check-compatibility pour vérifier que le projet dispose de capacités côté serveur.

URL de base : https://api.dev.runwayml.com

Toutes les requêtes requièrent ces en-têtes :

Authorization: Bearer <RUNWAYML_API_SECRET>
X-Runway-Version: 2024-11-06

Modèles et endpoints

Génération vidéo

Durée vidéo : 2 à 15 secondes (dépend du modèle). Les rapports d'aspect sont basés sur les pixels : 1280:720, 720:1280, 1104:832, 960:960, 832:1104, 1584:672, etc.

Spécificités de Seedance 2 :

• Modes : text-to-video, image-to-video (première/dernière image ou référence d'image), video-to-video
• Durée : requise pour TTV et ITV (en secondes)
• Rapports d'aspect (basés sur pixels) : 1280:720, 720:1280, 960:960, 1112:834, 834:1112, 1470:630, 992:432, 864:496, 752:560, 640:640, 560:752, 496:864
• ITV supporte deux modes mutuellement exclusifs : première/dernière image (tableau promptImage avec position) ou référence d'image (tableau references)
• Exigences d'entrée VTV : max 15 secondes, max 32 Mo, min 720p, MP4 recommandé

Génération d'images

Génération audio

Personnages (Avatars en temps réel)

Endpoints :

Paramètres de création d'avatar :

Présets vocaux : clara (doux), victoria (ferme), vincent (autoritaire). Prévisualisez tous les présets sur dev.runwayml.com.

Statuts de session : NOT_READY → READY → RUNNING → COMPLETED (ou FAILED / CANCELLED)

Documents (Base de connaissances)

Chaque avatar supporte jusqu'à 50 000 tokens de connaissances. Liez des documents à un avatar via client.avatars.update(id, { documentIds: [...] }).

Référence du corps de requête (JSON brut)

À utiliser lors d'appels directs à l'API (par ex. via la commande request de use-runway-api) plutôt que via un SDK. Seuls les champs requis et courants sont affichés — consultez +rw-fetch-api-reference pour le schéma complet.

POST /v1/text_to_image

{
  "model": "gen4_image",
  "promptText": "A serene Japanese garden with cherry blossoms",
  "ratio": "1920:1080"
}

• model : gen4_image | gen4_image_turbo | gemini_2.5_flash (requis)
• promptText : chaîne, jusqu'à ~1 000 caractères (requis)
• ratio : l'un de 1920:1080, 1080:1920, 1024:1024, 1360:768, 1080:1080, 1168:880, 1440:1080, 1080:1440, 1808:768, 2112:912 (requis ; variantes 720p ou 1080p selon le modèle)
• referenceImages : optionnel [{ "uri": "https://...", "tag": "MyTag" }] — référencer par @MyTag dans promptText
• seed : entier optionnel pour la reproductibilité

POST /v1/text_to_video

{
  "model": "gen4.5",
  "promptText": "A golden retriever running through wildflowers at sunset",
  "ratio": "1280:720",
  "duration": 5
}

• model : gen4.5 | veo3 | veo3.1 | veo3.1_fast | seedance2 (requis)
• duration : entier en secondes, 2–10 (requis ; valeurs valides spécifiques au modèle — par ex. veo3 accepte uniquement 8)
• ratio : par ex. 1280:720, 720:1280, 1104:832, 832:1104, 960:960 (requis)

POST /v1/image_to_video

{
  "model": "gen4.5",
  "promptImage": "https://example.com/cover.jpg",
  "promptText": "A slow dolly-in shot",
  "ratio": "1280:720",
  "duration": 5
}

• model : gen4.5 | gen4_turbo | veo3 | veo3.1 | veo3.1_fast | seedance2 (requis)
• promptImage : URL HTTPS, URI de données, ou URI runway:// (requis). Peut aussi être [{ "uri": "...", "position": "first" | "last" }] pour des keyframes.
• promptText : optionnel pour la plupart des modèles, requis pour gen4_turbo quand aucun mouvement d'image n'est évident

POST /v1/video_to_video

{
  "model": "gen4_aleph",
  "videoUri": "https://example.com/source.mp4",
  "promptText": "Change the season to winter with snowfall",
  "ratio": "1280:720"
}

POST /v1/text_to_speech

{
  "model": "eleven_multilingual_v2",
  "text": "Hello, welcome to Runway.",
  "voice": { "type": "runway-preset", "presetId": "clara" }
}

• voice : { type: "runway-preset", presetId: "clara" | "victoria" | "vincent" | ... } ou objet de voix spécifique au fournisseur
• languageCode : code ISO optionnel (auto-détecté par défaut)

POST /v1/sound_effect

{
  "model": "eleven_text_to_sound_v2",
  "promptText": "Thunderclap followed by heavy rain",
  "duration": 5
}

POST /v1/voice_isolation

{
  "model": "eleven_voice_isolation",
  "audioUri": "https://example.com/noisy.mp3"
}

POST /v1/voice_dubbing

{
  "model": "eleven_voice_dubbing",
  "audioUri": "https://example.com/english.mp3",
  "targetLanguage": "es"
}

POST /v1/speech_to_speech

{
  "model": "eleven_multilingual_sts_v2",
  "audioUri": "https://example.com/source.mp3",
  "voice": { "type": "runway-preset", "presetId": "victoria" }
}

POST /v1/avatars

{
  "name": "Support Agent",
  "referenceImage": "https://example.com/portrait.jpg",
  "voice": { "type": "runway-live-preset", "presetId": "clara" },
  "personality": "You are a friendly support agent.",
  "documentIds": []
}

POST /v1/documents

{
  "avatarId": "<avatar-id>",
  "name": "FAQ",
  "content": "Q: What is your return policy?\nA: 30 days, no questions asked."
}

POST /v1/realtime_sessions

{
  "avatarId": "<avatar-id>"
}

Endpoints de gestion

Cycle de vie des tâches

Tous les endpoints de génération renvoient un objet tâche. Le flux est :

1. Soumettre — POST /v1/<endpoint> → retourne { "id": "task_xxx" }
2. Faire un polling — GET /v1/tasks/{id} → retourne la tâche avec son status
3. Récupérer la sortie — Quand status === "SUCCEEDED", le tableau output contient des URLs signées

Statuts de tâche

Polling SDK (recommandé)

Les SDKs fournissent une méthode waitForTaskOutput() qui gère le polling automatiquement :

// Node.js — fait un polling jusqu'au terme (délai d'expiration par défaut 10 min)
const task = await client.imageToVideo.create({
  model: 'gen4.5',
  promptImage: 'https://example.com/image.jpg',
  promptText: 'A sunset timelapse',
  ratio: '1280:720',
  duration: 5
}).waitForTaskOutput();

console.log(task.output); // Tableau d'URLs signées

# Python
task = client.image_to_video.create(
    model='gen4.5',
    prompt_image='https://example.com/image.jpg',
    prompt_text='A sunset timelapse',
    ratio='1280:720',
    duration=5
).wait_for_task_output()

print(task.output)

Polling manuel (REST)

async function pollTask(taskId) {
  while (true) {
    const response = await fetch(`https://api.dev.runwayml.com/v1/tasks/${taskId}`, {
      headers: {
        'Authorization': `Bearer ${process.env.RUNWAYML_API_SECRET}`,
        'X-Runway-Version': '2024-11-06'
      }
    });
    const task = await response.json();

    if (task.status === 'SUCCEEDED') return task;
    if (task.status === 'FAILED') throw new Error(task.failure);

    await new Promise(r => setTimeout(r, 5000)); // polling chaque 5 secondes
  }
}

Gestion de la sortie

• Les tâches réussies retournent un tableau output avec des URLs signées vers le contenu généré
• Les URLs de sortie expirent dans 24-48 heures
• Téléchargez et stockez les sorties dans votre propre stockage — ne servez pas les URLs signées aux utilisateurs finaux
• Les sorties vidéo sont en MP4, les sorties images en PNG/JPEG

Exigences d'entrée

Limites de taille

Formats supportés

• Images : JPEG, PNG, WebP (pas de GIF)
• Codecs vidéo : H.264, H.265/HEVC, AV1, VP8/VP9, Apple ProRes, Theora
• Audio : MP3, AAC, FLAC, PCM, ALAC

Exigences pour les URLs

Si vous fournissez des ressources via URL :

• HTTPS uniquement (pas de HTTP)
• Noms de domaine uniquement (pas d'adresses IP)
• Pas de redirections
• Doit supporter les requêtes HTTP HEAD
• Doit retourner des en-têtes Content-Type et Content-Length valides
• Longueur max d'URL : 2 048 caractères

Limites de débit et tiers

• Pas de limite de requêtes par minute — uniquement des quotas de génération quotidiens
• Dépasser la concurrence → statut THROTTLED (mise en file d'attente automatique, pas de rejet)
• Dépasser la limite quotidienne → 429 Too Many Requests
• Les limites quotidiennes utilisent une fenêtre mobile de 24 heures

Gestion des erreurs

Erreurs HTTP

Codes d'échec de tâche

Les SDKs gèrent automatiquement les tentatives pour les erreurs transitoires.

Support des URI de données

Les images encodées en base64 peuvent être passées à la place des URLs :

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

Utile pour les petites images ou quand vous ne voulez pas héberger le fichier. Soumis aux limites de taille des URI de données ci-dessus.