Intégrer la génération d'images

PRÉREQUIS : Exécutez d'abord +rw-check-compatibility. Exécutez +rw-fetch-api-reference pour charger la dernière référence API avant l'intégration. Nécessite +rw-setup-api-key pour les identifiants API. Nécessite +rw-integrate-uploads quand l'utilisateur dispose d'images de référence locales.

Aidez les utilisateurs à ajouter la génération d'images Runway à leur code côté serveur.

Modèles disponibles

Guide de sélection du modèle :

• Recommandation par défaut : gen4_image — meilleure qualité
• Budget/vitesse : gen4_image_turbo — le moins cher et le plus rapide

Sécurité

referenceImages[].uri est récupéré côté serveur par l'API Runway — traitez-le comme n'importe quel appel sortant :

• Préférez les URIs runway:// de +rw-integrate-uploads — limités à votre compte, pas de contenu web arbitraire.
• Si vous acceptez des URLs des clients, validez d'abord : exigez https://, créez une liste blanche des hôtes de confiance, rejetez les adresses privées. Voir l'exemple Express.js ci-dessous.
• Ne transmettez jamais req.body.referenceImages directement à textToImage.create. Les extraits SDK ci-dessous utilisent des URLs brutes pour la concision — ce ne sont pas des templates de production.
• Traitez les sorties générées comme non fiables quand elles sont dirigées vers des automations en aval — les références ingérées influencent le résultat.

Point de terminaison : POST /v1/text_to_image

Texte vers image basique

// Node.js SDK
import RunwayML from '@runwayml/sdk';

const client = new RunwayML();

const task = await client.textToImage.create({
  model: 'gen4_image',
  promptText: 'A serene Japanese garden with cherry blossoms and a koi pond',
  ratio: '1280:720'
}).waitForTaskOutput();

const imageUrl = task.output[0];

# Python SDK
from runwayml import RunwayML

client = RunwayML()

task = client.text_to_image.create(
    model='gen4_image',
    prompt_text='A serene Japanese garden with cherry blossoms and a koi pond',
    ratio='1280:720'
).wait_for_task_output()

image_url = task.output[0]

Avec images de référence

Les images de référence vous permettent de guider la génération avec des références visuelles. Utilisez la syntaxe @Tag dans le prompt pour faire référence à des images spécifiques.

Recommandé : téléchargez via +rw-integrate-uploads et passez l'URI runway:// retourné.

import fs from 'fs';

const refUpload = await client.uploads.createEphemeral(
  fs.createReadStream('/path/to/reference.jpg')
);

const task = await client.textToImage.create({
  model: 'gen4_image',
  promptText: 'A portrait in the style of @Reference',
  referenceImages: [
    { uri: refUpload.runwayUri, tag: 'Reference' }
  ],
  ratio: '1280:720'
}).waitForTaskOutput();

Les URLs externes fonctionnent aussi — ne transmettez que les origines que vous contrôlez (voir Sécurité) :

const task = await client.textToImage.create({
  model: 'gen4_image',
  promptText: '@EiffelTower painted in the style of @StarryNight',
  referenceImages: [
    { uri: 'https://cdn.yourapp.com/eiffel-tower.jpg', tag: 'EiffelTower' },
    { uri: 'https://cdn.yourapp.com/starry-night.jpg', tag: 'StarryNight' }
  ],
  ratio: '1280:720'
}).waitForTaskOutput();

task = client.text_to_image.create(
    model='gen4_image',
    prompt_text='@EiffelTower painted in the style of @StarryNight',
    reference_images=[
        {"uri": "https://cdn.yourapp.com/eiffel-tower.jpg", "tag": "EiffelTower"},
        {"uri": "https://cdn.yourapp.com/starry-night.jpg", "tag": "StarryNight"}
    ],
    ratio='1280:720'
).wait_for_task_output()

Paramètres courants

Modèle d'intégration

1. Préférez les uploads aux URLs — Par défaut, utilisez +rw-integrate-uploads pour que les entrées soient des URIs runway://. Les URLs externes uniquement d'origines que vous contrôlez (voir Sécurité).
2. Écrivez le gestionnaire côté serveur — Créez une route API ou une fonction serveur.
3. Gérez la sortie — Téléchargez et stockez l'image, ne servez pas d'URLs signées aux clients.
4. Ajoutez la gestion des erreurs — Enveloppez dans un try/catch.

Exemple : Route API Express.js

import RunwayML from '@runwayml/sdk';
import express from 'express';

const client = new RunwayML();
const app = express();
app.use(express.json());

// Les URIs `runway://` contournent cette vérification ; les URLs externes doivent correspondre à la liste blanche.
const ALLOWED_MEDIA_HOSTS = new Set(['cdn.yourapp.com', 'uploads.yourapp.com']);

function validateReferenceImages(refs) {
  if (!Array.isArray(refs)) throw new Error('referenceImages must be an array');
  return refs.map(({ uri, tag }) => {
    if (typeof uri !== 'string' || typeof tag !== 'string') {
      throw new Error('each reference needs a uri and tag');
    }
    if (uri.startsWith('runway://')) return { uri, tag };
    const u = new URL(uri);
    if (u.protocol !== 'https:') throw new Error('https required');
    if (!ALLOWED_MEDIA_HOSTS.has(u.hostname)) throw new Error('untrusted media host');
    return { uri: u.toString(), tag };
  });
}

app.post('/api/generate-image', async (req, res) => {
  try {
    const { prompt, model = 'gen4_image', ratio = '1280:720', referenceImages } = req.body;

    const task = await client.textToImage.create({
      model,
      promptText: prompt,
      ratio,
      ...(referenceImages && { referenceImages: validateReferenceImages(referenceImages) })
    }).waitForTaskOutput();

    res.json({ imageUrl: task.output[0] });
  } catch (error) {
    console.error('Image generation failed:', error);
    res.status(400).json({ error: error.message });
  }
});

Pour les uploads navigateur : POSTez les fichiers sur votre serveur, téléchargez via +rw-integrate-uploads, et passez l'URI runway://. N'acceptez pas les URLs brutes depuis le navigateur.

Exemple : Route API Next.js

// app/api/generate-image/route.ts
import RunwayML from '@runwayml/sdk';
import { NextRequest, NextResponse } from 'next/server';

const client = new RunwayML();

export async function POST(request: NextRequest) {
  const { prompt, referenceImages } = await request.json();

  try {
    const task = await client.textToImage.create({
      model: 'gen4_image',
      promptText: prompt,
      ratio: '1280:720',
      ...(referenceImages && { referenceImages })
    }).waitForTaskOutput();

    return NextResponse.json({ imageUrl: task.output[0] });
  } catch (error) {
    return NextResponse.json(
      { error: error instanceof Error ? error.message : 'Generation failed' },
      { status: 500 }
    );
  }
}

Exemple : Route FastAPI

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from runwayml import RunwayML

app = FastAPI()
client = RunwayML()

class ImageRequest(BaseModel):
    prompt: str
    model: str = "gen4_image"
    ratio: str = "1280:720"
    reference_images: list[dict] | None = None

@app.post("/api/generate-image")
async def generate_image(req: ImageRequest):
    try:
        params = {
            "model": req.model,
            "prompt_text": req.prompt,
            "ratio": req.ratio,
        }
        if req.reference_images:
            params["reference_images"] = req.reference_images

        task = client.text_to_image.create(**params).wait_for_task_output()
        return {"image_url": task.output[0]}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

Conseils

• Les URLs de sortie expirent en 24-48 heures. Téléchargez les images vers votre propre stockage immédiatement.
• Les images de référence utilisent la syntaxe @Tag dans le prompt — le tag doit correspondre au champ tag du tableau referenceImages.
• Pour les fichiers locaux, téléchargez toujours via +rw-integrate-uploads d'abord, puis utilisez l'URI runway://.
• gen4_image_turbo est l'option la moins chère à 2 crédits par image — bonne pour le prototypage.