Videos mit der PageToVid-API automatisieren

Rendern läuft asynchron: Ein Film dauert Minuten, also dreht sich die API um eine ID, mit der du später wiederkommst.

Ablehnungen kosten nichts und nennen den Grund: eine Seite hinter einer Bot-Prüfung oder mit HTTP-Fehler, eine private Adresse, ein leeres Guthaben (402, NO_CREDITS) oder ein Tarif ohne API (402, UPGRADE_REQUIRED). Lies den code und überspring den Eintrag; eine abgelehnte Seite in einer Schleife neu zu versuchen, ändert nichts, solange sich die Seite nicht ändert.

Erreicht ein Rendering done, held, error oder cancelled, schicken wir ein JSON-Event an seine callbackUrl (oder an den Standard-Webhook des Kontos). Jedes Event trägt drei Header: X-PageToVid-Timestamp, X-PageToVid-Signature und X-PageToVid-Event-Id.

Dein Empfänger sollte:

1. 1HMAC-SHA256 mit deinem Secret über Zeitstempel, Punkt und den rohen Body neu berechnen und in konstanter Zeit mit dem sha256=-Wert vergleichen. Das JSON erst danach parsen, nie vorher.
2. 2Einen Zeitstempel ablehnen, der älter als fünf Minuten ist. Das ist ein Replay.
3. 3Über die Event-ID deduplizieren: Dasselbe Event kommt nie unter zwei IDs, kann aber mehrfach ankommen.
4. 4Schnell mit 2xx antworten und die Veröffentlichung danach erledigen.

Die Zustellung wird dreimal im Abstand weniger Sekunden versucht, Weiterleitungen werden nicht verfolgt: Richte den Callback direkt auf deinen Empfänger. Hast du ein Event verpasst, kennt der Status-Endpunkt die Antwort trotzdem. Wir haben das so gebaut, nachdem wir Integrationen fünfzehn Minuten lang pollen sahen; der Webhook ersetzt die Schleife.

MolForge (molforge.ai) sagt ADMET-Eigenschaften von Molekülen voraus, bevor jemand sie synthetisiert. Der 16:9-Film läuft 27 Sekunden, fünf Szenen, 43 englische Wörter. Er beginnt mit einem KI-Clip einer Chemikerin allein im nächtlichen Labor zu „Months at the bench. Weeks of assays.“, schneidet auf eine Hand im Handschuh, die ein gescheitertes Fläschchen wegwirft („Then the molecule fails anyway“), dann eine Chat-Karte, in der MolForge ein vollständiges Profil liefert und Risiken vor jeder Synthese markiert. Eine Große-Zahl-Karte zeigt 92M+ Verbindungen zum Durchsuchen und Screenen. Der letzte Clip zeigt eine Chemikerin in einem hellen Labor vor einem 3D-Molekül: „Fail fast. On screen, not in the lab.“

Dieser Film ist ein geschriebenes Storyboard, als Animation gerendert, ohne gefilmte Seite. Für die Automatisierung ist das wichtig: /api/v1/videos nimmt eine URL und filmt sie, während ein Storyboard, das du selbst erzeugst (aus einem Changelog, einem Datensatz, einem Produkt-Feed), über das Tool create_animation des MCP-Endpunkts läuft, mit demselben Schlüssel. Siehe Videos mit Claude über MCP erstellen.

Die 9:16-Fassung läuft 29 Sekunden und fügt vor dem Scheitern einen Moment ein: „Your best candidate, finally ready“. Wir haben sie als zweites Storyboard geschrieben, weil die Hochkant-Fassung diese Pause brauchte. Wenn sich das Skript nicht ändert, fordere beide Formate in einem Aufruf mit outputs an.

Die meisten Integrationen brauchen nur url, aspect und callbackUrl. Diese Felder lohnen sich als Nächstes.

Zwei weitere Türen mit demselben Schlüssel: POST /api/v1/videos/:id/translate macht pro Sprache einen neuen Film (bis zu 6 pro Aufruf, neu vertont und neu untertitelt; siehe Videos in mehrere Sprachen lokalisieren), und die Site-Endpunkte analysieren eine Domain und schlagen vor, welche Seiten einen Film verdienen, mit kostenloser Vorschau vor dem Start.

Ein Rendering kostet 40 Credits, egal wie lang; jedes zusätzliche Format ist ein weiteres Rendering; Entwürfe sind kostenlos; KI-Clips und -Bilder kommen dazu und werden vor dem Ausgeben beziffert (siehe Credits und was ein Video kostet). Einen Preis pro Aufruf gibt es nicht; die Tarifpreise stehen unter Preise. Ein Konto kann zehn Renderings pro Minute starten, ein Stapel von zweihundert ist also eine Warteschlange, kein Ansturm: abschicken, ID speichern, Webhooks zurückkommen lassen. Ein Rendering, das aus technischen Gründen scheitert, wird automatisch erstattet.

Die Fehler, die wir in echten Integrationen sehen:

• Wiederholen ohne Idempotency-Key. Ein Timeout bei dir heißt nicht, dass das Rendering nicht gestartet ist. Ohne Schlüssel ist der zweite Versuch ein zweiter Film und eine zweite Abbuchung.
• Neu rendern per Cronjob. Ein nächtlicher Job über einen unveränderten Katalog zahlt jede Nacht für denselben Film. Löse bei Änderungen aus: neues Produkt, neuer Preis, neues Release.
• Nur auf done hin veröffentlichen. Ein fertiger Film kann Warnungen tragen: eine Szene, die auf eine Karte zurückgefallen ist, eine langsam geladene Seite. Filtere nach hasWarnings und Score oder stell qualityGate auf Zurückhalten.

Und sortiere, bevor du generierst: Ein Film auf einer Seite, die niemand besucht, sind 40 Credits für nichts. Fang mit deinen meistbesuchten Seiten an, wie im Anwendungsfall E-Commerce-Video-Anzeigen, miss, dann erweitere.