Exécuter des modèles AI sur Replicate avec predictions et webhooks

Docs

Référence : https://replicate.com/docs/llms.txt
Schéma OpenAPI : https://api.replicate.com/openapi.json
Serveur MCP : https://mcp.replicate.com
Docs par modèle : https://replicate.com/{owner}/{model}/llms.txt
Définissez Accept: text/markdown lors de la demande de pages de documentation pour des réponses Markdown.

Choisir le bon modèle - Recherchez via l'API ou demandez à l'utilisateur.
Récupérer les métadonnées du modèle - Récupérez le schéma d'entrée et de sortie via l'API.
Créer une prediction - POST vers /v1/predictions.
Interroger les résultats - GET prediction jusqu'à ce que le statut soit "succeeded".
Retourner la sortie - Généralement des URLs vers le contenu généré.

Créer une prediction, stocker son id depuis la réponse, et interroger jusqu'à la fin.
Définir un header Prefer: wait lors de la création d'une prediction pour une réponse synchrone bloquante. Recommandé uniquement pour les modèles très rapides. Maximum 60 secondes.
Définir une URL de webhook HTTPS lors de la création d'une prediction, et Replicate effectuera un POST sur cette URL quand la prediction sera terminée.

Utilisez l'endpoint POST /v1/predictions, car il supporte les modèles officiels et communautaires.
Chaque modèle a son propre schéma OpenAPI. Récupérez et vérifiez toujours les schémas des modèles pour vous assurer que vous définissez des entrées valides. Même les modèles populaires changent leurs schémas.
Validez les paramètres d'entrée par rapport aux contraintes du schéma (minimum, maximum, valeurs enum). Ne générez pas de valeurs qui les violeraient.
Quand vous n'êtes pas sûr d'une valeur de paramètre, utilisez l'exemple par défaut du modèle ou omettez le paramètre optionnel.
Ne définissez les entrées optionnelles que si vous avez une raison de le faire. Concentrez-vous sur les entrées obligatoires et laissez les valeurs par défaut du modèle fonctionner.
Utilisez des URLs HTTPS pour les entrées de fichiers autant que possible. Vous pouvez aussi envoyer des fichiers encodés en base64, mais ils doivent être évités.
Lancez plusieurs predictions en parallèle. N'attendez pas qu'une se termine avant de commencer la suivante.
Les URLs des fichiers de sortie expirent après 1 heure, donc sauvegardez-les si vous avez besoin de les conserver, en utilisant un service comme Cloudflare R2.
Les webhooks sont un bon mécanisme pour recevoir et stocker la sortie des predictions.

Une prediction passe par ces états : starting -> processing -> succeeded / failed / canceled.
Les modèles officiels utilisent le format owner/name. Les modèles communautaires nécessitent owner/name:version_id.
L'endpoint POST /v1/predictions gère les deux.

Définissez webhook sur une URL HTTPS lors de la création d'une prediction. Replicate effectue un POST de l'objet prediction complet quand elle se termine.
Filtrez les événements avec webhook_events_filter : start, output, logs, completed.
Validez les signatures des webhooks en utilisant les headers Webhook-ID, Webhook-Timestamp et Webhook-Signature. Récupérez le secret de signature depuis GET /v1/webhooks/default/secret.

Définissez lifetime pour annuler automatiquement les predictions qui durent trop longtemps (par ex. 30s, 5m, 1h). Mesuré à partir du moment de création.

Les modèles de langage qui supportent le streaming incluent une URL stream dans la réponse. Utilisez SSE pour recevoir la sortie incrémentale.

Privilégiez les URLs HTTPS pour les entrées de fichiers. Les URLs de sortie d'une prediction peuvent être passées directement en entrée fichier au modèle suivant.
Les URLs des fichiers de sortie expirent après 1 heure. Téléchargez-les et stockez-les immédiatement si vous avez besoin de les conserver.

Enchaînez les modèles en passant les URLs de sortie en tant qu'entrées fichier au modèle suivant.
Lancez toutes les predictions indépendantes en parallèle, puis collectez les résultats.
Les URLs de sortie sont valides pendant 1 heure, ce qui est suffisant pour les étapes de pipeline.