Communitygithub.com

riffkit/skills

Verwandle einen viralen TikTok in dein eigenes Video: dieselbe Emotionsformel, dein Produkt, neues Filmmaterial. Füge den Link ein (oder lade das Video hoch), wähle optional ein Produkt, einen Charakter und eine Sprache aus, und das Backend erstellt die Aufmerksamkeitsstruktur (Hook, Beat-Struktur, Dialog-Timing) neu, basierend auf deinem Inhalt. Du riffst die Formel, nicht das Video. Auslöser: 'riff this video', 'riff this TikTok', 'turn this TikTok into mine', 'remake this viral video with my product', 'recreate this video for my brand'.

Was ist skills?

Diese KI-Agenten-Fähigkeit ermöglicht es, virale TikTok-Videos zu analysieren und ihre emotionale Formel auf eigene Inhalte zu übertragen – ohne das Originalvideo zu kopieren. Der Agent unterstützt drei Modi: **Adapt** (Standard: analysiert die Emotionsformel eines Quellvideos und erstellt eine neue Geschichte mit eigenem Filmmaterial), **Swap** (behält die Einstellungen, Schnitte und das Timing des Originals bei, tauscht aber Charaktere, Produkte oder Szenen aus) und **Creation** (erstellt ein originelles Werbevideo aus einer schriftlichen kreativen Anweisung). Die Fähigkeit ist für Claude Code, Cursor und ähnliche KI-Codierungsagenten optimiert. Der Agent identifiziert die Quelle (TikTok-Link, hochgeladenes Video oder analysierte Vorlage), schlägt optionale Einstellungen vor (Charakter, Produkt, Sprache, creative direction) und holt vor dem Absenden eine explizite Bestätigung ein. Der wichtigste strategische Freiheitsgrad ist `content_anchor` – die kreative Anweisung, welchen Produktnutzen oder welche Oberfläche die Emotionsformel füllen soll. Der Agent überwacht den Fortschritt (alle 10-15s), liefert das fertige Video mit Download-Link und Beschreibung aus und behandelt Fehler (HTTP 402 bei fehlendem Guthaben) transparent, ohne automatische Wiederholungen.

Funktioniert mit✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/riffkit/skills/tree/HEAD/riff-viral-tiktok

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Riffkit-Fähigkeit

Kernprinzip: Du riffst die Formel, nicht das Video. Gib eine erfolgreiche Quelle an; das Backend analysiert die Emotionsformel, die die Aufmerksamkeit kapert, und überträgt diese Formel auf deine eigenen Inhalte. Das Filmmaterial kann völlig anders sein, solange der Betrachter denselben psychologischen Pfad durchläuft.

Oder behalte das Filmmaterial: Swap-Modus (mode=swap). Wenn der Benutzer die genauen Einstellungen des Originals anstelle seiner Formel haben möchte ("setz mich in dieses Video", "gleiches Video, mein Charakter"), ersetzt ein Swap die Quelle Fenster für Fenster mit eigenem Timing: Kamera, Schnitte, Bildausschnitt, Aktion und Timing bleiben; was sich ändert, ist das, was der Benutzer benennt: ein digitaler Charakter anstelle der Person (kein Charakter = die ursprüngliche Person bleibt), ein Produkt und content_anchor für alles andere (Schauplatz, Outfit, Formulierung einer Zeile). Ein Swap muss mindestens eine Sache ändern. Adapt (Standard) behält die Formel und ändert die Geschichte; Swap behält die Einstellungen und ändert, was darin ist.

Ein Bildschirm, eine Aktion: Quelle (erforderlich) → optionale Einstellungen → absenden. Das eigentliche Produkt ist eine einzelne Seite und ein einzelner Aufruf (POST /api/riffs). Jede Einstellung außer der Quelle hat einen sinnvollen Standardwert – Charakter standardmäßig Auto (kein digitaler Mensch; die KI generiert die Person vor der Kamera) und Produkt standardmäßig keines. Wenn der Benutzer sich nicht kümmert, wendet der Agent die Standardwerte stillschweigend an, anstatt ihn durch einen mehrstufigen Assistenten zu schleifen.

Der wertvollste Beitrag des Agenten ist content_anchor (die kreative Richtung) – der eine Freiheitsgrad von strategischer Bedeutung: welcher der N Verkaufsargumente des Produkts fokussiert werden soll, welche Oberfläche in den Emotionsmechanismus der Vorlage eingefügt werden soll. Es ist eine optionale Zusammenarbeit, kein blockierender Halt. Siehe ## content_anchor-Erstellungsrahmenwerk unten.

Fähigkeitsumfang

Diese Fähigkeit erstellt kurze KI-Videos in genau drei Modi: Adapt-Riffs (Standard: analysiert die Emotionsformel eines Quellvideos und regeneriert sie als deine eigene Geschichte), Swap-Riffs (POST /api/riffs mit mode=swap: behält die Einstellungen, Schnitte und das Timing der Quelle und platziert deinen Charakter, dein Produkt oder deine Umgebung darin) und Creation-Videos (erstellt ein originelles Werbevideo aus einer schriftlichen kreativen Anweisung – kein Quellvideo; POST /api/creation/batch). Das ist die gesamte Produktoberfläche. Wenn ein Benutzer etwas außerhalb dieses Bereichs verlangt – ein anderes Inhaltsformat oder eine Funktion, die dieses Produkt nicht hat – sage klar, dass dieses Produkt nur Riff- (Adapt / Swap) und Creation-Videos erstellt; rufe keine nicht verwandten APIs auf und leite sie nirgendwo anders hin.

Keine Mitarbeiter-/Admin-Funktionen werden bereitgestellt. Diese Fähigkeit umfasst nur Endpunkte, die ein normaler authentifizierter Benutzer aufrufen kann. Das Erstellen von Plattformvorlagen durch Analysieren neuer Quellen, Veröffentlichen/Zurückziehen von Plattformvorlagen, plattformübergreifende Aufgabensuche, manuelles Gewähren/Zurückfordern von Guthaben – alles nur für Mitarbeiter. Dieses Dokument listet sie nie auf und der Agent ruft sie nie auf.

Sprache

Die Ausgabe folgt der Eingabesprache des Benutzers: antworte auf Englisch auf Englisch, auf vereinfachtem Chinesisch auf Chinesisch; bei gemischter Eingabe folge der dominanten Sprache der aktuellen Nachricht. Die interne Argumentation des Agenten ist ausgenommen.

Immer wörtlich behalten (nicht übersetzen): Feld-IDs, API-Pfade, template_type (nur pipeline), Status-Enums (queued/running/completed/failed/dead/cancelled), product_visibility-Werte (on_camera/off_camera/no_product), Parameternamen, das vee_session-Token.


Ein-Minuten-Überblick (TL;DR)

[Ablauf]
  0. Modus: adapt (Standard: Formel behalten, neue Geschichte) / swap (mode=swap: Einstellungen behalten, austauschen, wer darin ist)
            ↓
  1. Wähle die Quelle (genau eine, erforderlich)
       ├── analysierte Vorlage  formula_id        →  überspringt Analyse, generiert sofort (am schnellsten)
       ├── TikTok-Link        tiktok_url        →  Backend lädt herunter + analysiert + generiert
       ├── hochgeladenes Video     video (≤100MB, ≤ Render-Limit) →  Backend analysiert + generiert
       └── eigenes fertiges Video source_asset_id   →  NUR SWAP: eines deiner fertigen Riff-/Creation-Videos
            ↓
  2. Optionale Einstellungen (alle standardmäßig; Agent kann vorschlagen, nie erzwingen)
       character     Standard Auto (KI-generierte Person); kann einen passenden Charakter basierend auf der Kontoabsicht vorschlagen
                     (Swap: optional; kein Charakter = die ursprüngliche Person bleibt. Ein Swap muss dennoch etwas
                      ändern: einen Charakter, ein Produkt mit Bildern oder eine schriftliche content_anchor)
       product       Standard none (no_product); ein vorhandenes/neues Produkt anhängen, um eines zu platzieren
       visibility    Standard on_camera; nur sinnvoll, wenn ein Produkt angehängt ist
       language      Standard en; Kandidaten von GET /api/languages (derzeit en / es / pt / id / de / fr / it / ja / zh-CN)
                     (Swap ignoriert Sprache / Sichtbarkeit / Seitenverhältnisse: die Quelle bestimmt sie)
       content_anchor optionale kreative Richtung; Agent kann proaktiv einen Entwurf zur Überprüfung erstellen
       user_hint     optionaler Hook-Hinweis; nur für eine NEUE Quelle verwendet (für eine Vorlage ignoriert)
            ↓
  3. Vor dem Absenden bestätigen (der einzige harte Stopp)  →  POST /api/riffs
            ↓  ↳ unzureichendes Guthaben gibt HTTP 402 zurück (strukturiert); behandeln gemäß "Abrechnung & Guthaben"
  4. Überwachen  GET /api/tasks/batch/{batch_id}  (alle 10-15s)
            ↓
  5. Ausliefern  GET /api/assets → Download-Links + Bildunterschrift + Hashtags + Strategie-Zusammenfassung

Der einzige harte Stopp ist die eine Bestätigung vor dem Absenden (die finanzielle Verpflichtung). Charakter, Produkt und content_anchor sind optionale Zusammenarbeiten und blockieren niemals den Ablauf.

Endpunkte auf einen Blick:

EndpunktZweck
GET /api/auth/meAuthentifizierungsstatus prüfen
POST /api/skill/device/authorize · POST /api/skill/device/tokenEin-Klick-Anmeldung (Geräteautorisierung; kein Token-Einfügen)
POST /api/riffsEinmaliger Riff (der bevorzugte, nahezu einzige Generierungseinstieg)
GET /api/formulasAnalysierte Vorlagen auflisten (eine der Quellen)
GET /api/formulas/{id}extraction_summary einer Vorlage (was extrahiert wurde)
POST /api/formulas/analyzeNur für Abonnenten – eine neue Quelle in deine eigene Vorlage analysieren ohne zu generieren (eine Bibliothek aufbauen)
POST /api/formulas/{id}/refresh-analysisEine deiner eigenen Vorlagen erneut analysieren (veraltet, oder ihr Hinweis war falsch)
PATCH /api/formulas/{id}Eine deiner eigenen Vorlagen umbenennen oder ihren user_hint ändern (dann aktualisieren)
GET /api/charactersDigitale Charaktere (optionale Bindung) – Erstellung ist begrenzt, siehe "Erstellungslimits"
GET /api/products · POST /api/products · POST /api/products/{id}/imagesProdukte + Produktbilder (optionale Platzierung) – Erstellung ist begrenzt
GET /api/settingsBereitstellungsfähigkeiten + die creation_limits dieses Kontos (Vorprüfung vor dem Erstellen eines Charakters/Produkts/Avatars) + credit_cover ({available, adapt, swap, trial}: das längste eigene Video in ganzen Sekunden, das das Guthaben in jedem Modus mit der Standard-Engine dieses Modus abdeckt; zitiere es in Guthaben und Sekunden, niemals in Dollar)
GET /api/languagesVideo-Sprachkandidaten
GET /api/tasks/batch/{id} · GET /api/tasks/{id}Fortschrittsabfrage
GET /api/tasks · GET /api/tasks/statsAufgaben auflisten / zählen
POST /api/tasks/{id}/cancel · POST /api/tasks/{id}/retryAbbrechen / Wiederholen
GET /api/assetsFertige Videos abrufen (Video + Bildunterschrift + Hashtags)
POST /api/pipeline/backfill · GET /api/pipeline/backfill/occupiedZusätzliche Seitenverhältnisse zu einem bereits ausgelieferten Render hinzufügen (Reframe) / bereits erstellte Verhältnisse auflisten
GET /api/usage/creditsGuthaben
GET /api/billing/plans · GET /api/billing/subscriptionPlan-Katalog / aktueller Plan (für Upsell nach 402)

Vollständige Parameter und Antworten siehe "API-Referenz" unten.


Verhaltensregeln (harte Einschränkungen)

Der Agent sendet niemals selbstständig ab. Er hält einmal inne, um die explizite Zustimmung einzuholen, bevor er absendet. Alles andere kann mit Standardwerten fortfahren.

NICHT:

  • Eine Aufgabe automatisch absenden, nur weil der Benutzer "riff this" gesagt hat (die Quelle + Konfiguration zu entscheiden ist in Ordnung; das Absenden muss auf eine Freigabe warten)
  • "Wähle einen Charakter / wähle ein Produkt" als unüberspringbaren Schritt behandeln – Charakter standardmäßig Auto, Produkt standardmäßig none; verwende die Standardwerte, wenn der Benutzer keines davon verlangt hat (ein Swap muss dennoch mindestens eine Sache ändern, siehe Schritt 0)
  • Das Erstellen eines content_anchor-Entwurfs als harten Stopp behandeln, der zur Zufriedenheit des Benutzers iteriert werden muss, bevor es weitergeht (es ist eine optionale Zusammenarbeit)
  • Einen Preis selbst berechnen oder das Guthaben freiwillig nennen – jeder Preis kommt vom Server: GET /api/riffs/quote für einen Adapt- oder Swap-Riff (jede Quelle) und credits_per_ratio von GET /api/pipeline/backfill/occupied für zusätzliche Verhältnisse eines Videos, das du bereits hast. Ein Creation-Video hat kein Angebot und geht ohne Schätzung zur Bestätigung. Das Guthaben wird nur erwähnt, wenn das Angebot sagt, dass es den Preis nicht deckt (fits: false), bei einem 402, vor einer Wiederholung (die das Video, das erneut gerendert werden muss, erneut in Rechnung stellt, maximal den vollen Videopreis – siehe POST /api/tasks/{task_id}/retry), oder wenn der Benutzer fragt
  • Eine fehlgeschlagene Aufgabe automatisch wiederholen (eine Wiederholung kann Videosekunden erneut in Rechnung stellen; der Benutzer entscheidet)
  • Produktinformationen speichern, die der Benutzer nicht explizit bestätigt hat
  • Mitarbeiter-Endpunkte aufrufen oder hier nicht aufgeführte Pfade testen

TUE:

  • Zuerst die Quelle festlegen (eine von drei; im Swap-Modus auch dein eigenes fertiges Video) – die einzige erforderliche Eingabe
  • Vor dem Absenden den Plan zusammenfassen (Modus / Quelle / Charakter / Produkt+Sichtbarkeit / Sprache / content_anchor, plus den Preis von GET /api/riffs/quote für einen Adapt- oder Swap-Riff, siehe Schritt 3) und "Absenden?" fragen → bei Bestätigung POST /api/riffs aufrufen
  • Bei HTTP 402 dem Abschnitt "Abrechnung & Guthaben" folgen: topup_url wörtlich weitergeben, keine Wiederholung, kein stillschweigender Fehler
  • GET /api/usage/credits nur aufrufen, wenn der Benutzer fragt, wie viel Guthaben er noch hat, oder vor dem Angebot einer Wiederholung (um die maximalen Kosten mit dem Guthaben zu vergleichen); ein 402 enthält bereits beide Zahlen
  • Bei mehrdeutiger Eingabe nachfragen, anstatt zu raten und fortzufahren
  • Fehler ehrlich kommunizieren, sobald sie auftreten; niemals stillschweigend wiederholen
  • Bei einem fertigen Video nur den Download-Link + Text präsentieren – niemals auf einer Plattform veröffentlichen

Bis der Benutzer "absenden / generieren / riff / los" sagt, bist du ein Mitarbeiter, der einen Plan entwirft und präsentiert – kein Befehlsausführer.

Wer was tut. Du beurteilst und bearbeitest: wählst die Quelle, erstellst content_anchor und user_hint, korrigierst Untertitel und entscheidest, ob ein Ergebnis seinen Zweck erfüllt. Der Server misst und generiert: die Analyse, das Untertitel-Timing (align_status) und das Video; lies, was er meldet, anstatt es zu erraten. Jeder bezahlte Schritt (ein neuer Riff oder ein Creation-Video, eine Wiederholung, ein zusätzliches Verhältnis) wartet auf die Freigabe des Benutzers. Konvergiere: Sobald das Video seinen Zweck erfüllt, liefere es aus und benenne, was noch nicht perfekt ist (eine Bildunterschrift einen Beat zu spät, ein Gesicht, das sich nicht vollständig geändert hat), anstatt mehr Render-Durchläufe zu verschwenden, um null Fehler zu erreichen.


Kernidee: die drei Verantwortungsebenen (warum content_anchor den Wert des Agenten ausmacht)

EbeneRolleFestgelegt durchFreiheit
Formel + GrundgerüstBoden-Garantie – ein validierter Emotionsmechanismus + KameraspracheBei der VorlagenanalyseKeine (Ändern verliert den Wert des Riffs)
Charakter + ProduktBasis-Konstanten – der digitale Mensch + ProduktfaktenIn den Einstellungen gewählt (oder Standard)Unterschiedliche Auswahl = unterschiedliche Konstanten, aber innerhalb einer Aufgabe konstant
content_anchorDecken-Treiber – welcher Verkaufsargument-Winkel, welche zu füllende OberflächeAgent + Benutzer entwerfen gemeinsam (optional)Der eine Freiheitsgrad strategischer Bedeutung

Das Formel-Grundgerüst bestimmt, welchen psychologischen Pfad der Betrachter geht; content_anchor bestimmt, welcher spezifische Inhalt diesen Pfad füllt. Die anderen Ebenen sind bereits existierende Konstanten, also liegt der differenzierte Wert des Agenten darin, "Quellformel × Produkt/Konto × Charakter" zu einer konkreten kreativen Anweisung zu verschmelzen.


Vollständiger Arbeitsablauf

Schritt 0: Adapt oder Swap (Standard: Adapt)

ModusmodeWas bleibtWas ändert sichWähle ihn, wenn
Adapt (Standard)adapt oder weggelassenDie Emotionsformel: Hook, Rhythmus, BeatsDie Geschichte, Szenen, das Drehbuch, die SpracheDer Benutzer sein eigenes Video möchte, das wie der Gewinner funktioniert
SwapswapKamera, Schnitte, Bildausschnitt, Aktion, Timing, Ton und Bildformat der QuelleWas der Benutzer benennt: die Person (dein Charakter, falls du einen wählst), ein Produkt und was content_anchor benennt: die Umgebung, ein Outfit, die Formulierung einer ZeileDer Benutzer dieses Video mit seinem Charakter darin haben möchte ("gleiches Video, aber ich", "setz meinen Charakter in dieses hier")

Swap-Regeln (backend-erzwungen):

  • Ein Swap muss mindestens eine Sache ändern: einen Charakter (character_ids), ein Produkt mit Bildern (product_id; ein Produkt ohne Bilder ändert nichts) oder eine nicht leere content_anchor. Keines der drei → 400, dessen detail ein einfacher lokalisierter Satz ist (EN: "A swap needs at least one change: …"; der Body trägt keinen Fehlercode, also gib detail weiter, anstatt darauf zu matchen). Wird für jede Swap-Quelle geprüft, bevor etwas analysiert oder in Rechnung gestellt wird.
  • Der Charakter ist optional. Ohne Charakter bleibt die eigene Person der Quelle (ihr echtes Gesicht ist im Output); es gibt keine Auto-Person im Swap. Eine Aufgabe pro Charakter, wie bei Adapt; kein Charakter = eine Aufgabe. Ein gewählter Charakter benötigt einen genehmigten Avatar (has_any_active_avatar=true), wie bei Adapt. Wenn der Benutzer eine andere Person möchte, empfehle die Auswahl eines Charakters: Eine nur durch Worte in content_anchor geänderte Person hat kein Referenzbild, daher kann das Gesicht zwischen den Aufnahmen variieren (und bei Seedance 2.0 bleibt die Stimme des Originals erhalten).
  • Überprüfe den Avatar vor einem bezahlten Swap mit einem Charakter. Der Gesichtsaustausch funktioniert vom Avatarbild des Charakters (reference_image in GET /api/characters; rufe ${BASE_URL}${reference_image} mit dem Session-Cookie ab, wie die file_url eines Videos). Was funktioniert: ein klares, frontales Bild des Gesichts derselben Person wie der Charakter, mit guten Proportionen auf verschiedenen Bildschirmen. Was nicht funktioniert: Gruppenfotos, stark geneigte Köpfe, Gesicht zur Hälfte verdeckt, Cartoon anstelle eines echten Gesichts, Auflösung unter 512 × 512. Überprüfe, dass das Referenzbild geeignet ist, bevor du fortfährst (wenn nicht, weise den Benutzer an, ein besseres hochzuladen — es gibt kein reference_image-Bewertungsfeld). Der Avatar muss auf dem Account des Benutzers aktiv sein und zu einem dieser Gesichter passen; ohnehin folge dem GET /characters-Ergebnis.

Integration mit Streifen oben (Vorschläge): Vorlage, Charakter und Produkt können in der Nachricht oben angehängt sein. Wenn der Benutzer sie hat, muss der Agent dennoch die aktuellen Informationen vom Server abrufen (GET /api/formulas/{id}, /api/characters, /api/products), bevor er die Daten im Plan verwendet. Die Werte oben sind Hilfestellungen für die Navigation, nicht autoritative Bezugspunkte.


Schritt 1: Die Quelle

Drei Wege, eine Riff-Quelle einzureichen; wähle genau einen (Swap-Modus auch ein eigenes fertiges Video):

  1. Vorlagen-ID (formula_id). Eine bereits analysierte Vorlage. Das schnellste Mittel: Der Server überspringt die Analyse und generiert sofort. Informationen über eine Vorlage anzeigen = GET /api/formulas/{id}. Vorlagen auflisten = GET /api/formulas (dir gehören die, bei denen creator=="user"; der Benutzer kann sie umbenennen; extraction_summary von einer Vorlage zeigt die wichtigsten Beats; platform_templates=true, creator=="platform" sind plattformweit und nicht bearbeitbar).
  2. TikTok-URL (tiktok_url). Der Server lädt herunter, analysiert und generiert.
  3. Hochgeladene Videodatei (video). Bis zu 100 MB. Der Server analysiert und generiert (bei Überschreitung siehe Render-Limit unten).

Swap-Quelle. Wenn mode=swap: source_asset_id ist die ID eines fertigen Riff- oder Creation-Videos des Benutzers aus der Vermögensliste. Verwende NICHT formula_id oder tiktok_url oder video für einen Swap (der Server akzeptiert sie nicht).

Neue Vorlagen (für Abonnenten). POST /api/formulas/analyze extrahiert eine Vorlage aus einer neuen Quelle, ohne sofort zu generieren — baue eine Bibliothek auf, die später verwendet werden kann.

Render-Limit: Ein ungeschnittenes Quellvideo, das länger als 120 Sekunden ist, wird auf 120 Sekunden begrenzt (vorderes Ende). Der Benutzer kann stattdessen eine kürzere Quelle auswählen oder das Video vorher in einem Editor zuschneiden. Der Server akzeptiert maximal 120 Sekunden.


Schritt 2: Optionale Einstellungen

Alle Standardwerte, siehe Schritt-3-Bestätigung für den vollständigen Plan.

EinstellungTypStandardWie/wo man es bekommt
character_idsarray of string[] → AutoGET /api/characters
product_idstring oder nullnull → kein ProduktGET /api/products, POST /api/products (im Plan prüfen, dass ein Produkt, falls ausgewählt, Bilder hat; ohne Bilder ist es gleichbedeutend mit "kein Produkt")
product_visibilityenumon_cameraWird im Plan oder in /api/settings angezeigt; nur wenn product_id gesetzt ist sinnvoll
languageenumenGET /api/languages
content_anchorstring oder nullnullVom Agenten entworfen, siehe Rahmenwerk unten
user_hintstring oder nullnullOptionaler Hook-Hinweis, der an die Vorlagenanalyse übergeben wird; nur für eine neue Quelle (TikTok-Link oder hochgeladenes Video). Wenn der Benutzer einen bestimmten Hook im Kopf hat, gib diesen hier weiter, um die Analyse zu leiten (z. B. "Starte mit der Produktverpackung, die sich öffnet" wird den Hook auf dem geöffneten Objektiv verankern). Für Vorlagen ignoriert.
aspect_ratiostring"9:16" (hoch)Nur für Adapt/Creation (Swap ignoriert sie: die Quelle bestimmt die Form).
profilestring"default" (modusabhängig)Nur für Adapt (Swap ignoriert, Creation hat ihr eigenes).

Charakter ID(s): Der Standard [] bedeutet Auto: Der Server wählt einen vorhandenen digitalen Menschen oder generiert einen neuen. Wenn der Benutzer einen Charakter auswählt (einer aus GET /api/characters), verwende seine ID im Array. Ein Charakter, der beim Aufruf kein has_any_active_avatar=true hat (und somit kein Referenzgesichtsbild, wenn ein Avatar benötigt wird), kann die Generierung mit demselben 400-Fehler wie ohne Avatar-Erstellungskapazität fehlschlagen lassen. Siehe Erstellungslimits unten zum Erstellen eines neuen Charakters, Produkts oder Avatars. Ein Account kann anfangs keine Charaktere oder Produkte haben; du erstellst sie (auf Anfrage des Benutzers) mit den Basics und einem Bild als Standard. Der Account wird sie nach der ersten Erstellung in GET /api/characters und GET /api/products haben — sowie jedes Mal, wenn der Agent ihn abfragt. Ref. Erstellungslimits für Kapazitätsprüfung und Serverseite.

Produkt einbetten. Wenn ein Produkt angehängt ist (product_id) und product_visibility ist on_camera (Standard), platziert der Server es im Video (auf einem Tisch, in der Hand des Charakters, usw.). off_camera bedeutet, dass das Produkt nur im Voiceover und im Call-to-Action erwähnt wird.

Sprache. Nur für Adapt (Swap ignoriert die Sprache: Das Original behält seine eigene). Wähle den passenden Sprachcode aus GET /api/languages, nicht den String aus dem Benutzeranliegen.


Schritt 3: Vor dem Absenden bestätigen

Der eine harte Stopp. Rufe GET /api/riffs/quote mit den gesammelten Parametern auf, um die Kosten zu erhalten, dann präsentiere den Plan und frage.

Präsentiere einen Plan in dieser Form (übersetze die Werte, nicht die Feldnamen):

Modus:       adapt (Formel aus TikTok-Link)
Quelle:       [type] – [short desc]  (nicht die URL, nicht die gesamte Datei)
Charakter:    [character name] or Auto
Produkt:      [product name] or none
Sichtbarkeit: on_camera / off_camera
Sprache:      de
Richtung:     [content_anchor] or none
Preis:        [quoted] / your available [from the quote]
Den Plan absenden?

Das Angebot (GET /api/riffs/quote) hat den Body: {"estimated_credits": integer, "video_seconds": int (die geschätzte Sekundenzahl des generierten Videos — für Adapt basierend auf einer durchschnittlichen Zielrendite, für Swap die Dauer der Quelle), "fits": bool (ob die availablevon credit_cover den geschätzten Preis deckt; wennfalse, füge "Warnung: Dein Guthaben (X Credits) deckt diesen Riff nicht. Du wirst aufgefordert, nachzuladen." hinzu), "mode": string}. Zitiere Guthaben und Sekunden, niemals Dollar. Ehrlich sein: "Der Preis beträgt [estimated_credits] Credits, was etwa [video_seconds]s Video abdeckt."

Zur Bestätigung (und bevor du ein Angebot erhältst) rufe den Charakter als Vorschlag ab (vollständige Liste). Auf der Grundlage der Absicht des Kontos (welchen Charakter der Benutzer zu verwenden scheint) schlage einen vor. Wenn der Benutzer keinen angibt, ist es Auto. Stelle immer die Frage an den Benutzer, ob er einen Charakter auswählen möchte oder Auto behalten möchte. Gleiches gilt für das Produkt.

Wenn der Benutzer bestätigt, rufe POST /api/riffs mit denselben Parametern wie das Angebot auf. Das Angebot zu haben garantiert nicht, dass der Abschluss erfolgreich ist; das Guthaben kann sich zwischen Angebot und Abschluss ändern, aber behandele weiterhin 402 (siehe unten).

Wenn der Benutzer um einen Preis vor dem Angebot bittet, lade die Preise von GET /api/billing/plans und präsentiere sie dem Benutzer, anstatt zu raten. Kein Angebot, keine Zahlung; kein Festpreis; kein Dollar-Betrag.

Für Creation-Videos (POST /api/creation/batch): Kein Angebot; präsentiere den Plan ohne Preis und frage, bevor du absendest. Das ist kein Riff, also kein Riff-Angebot.


Schritt 4: Überwachen

Rufe GET /api/tasks/batch/{batch_id} alle 10–15 Sekunden ab. Der Status completed zeigt an, dass das Video fertig ist; verwende die Batch-id (keine einzelne Aufgaben-ID) für den nächsten Schritt. Bei Fehlschlag (failed) rufe GET /api/tasks/{task_id} ab, um die Fehlerdetails zu erhalten (gebe aber niemals rohen Backend-Text an den Benutzer weiter; fasse stattdessen den Fehler in natürlicher Sprache zusammen — "Die Analyse der Emotionen hatte ein Problem" anstelle des Textes der Ausnahme). Biete an, erneut zu versuchen (nachdem du das Guthaben überprüft hast — ein erneuter Versuch kann Sekunden erneut in Rechnung stellen, bis zum Preis des gesamten Videos). Erstelle KEINE neue Riff-Anfrage.

Ist das Video dead? Das bedeutet, das Rendering wurde für länger als eine Stunde angehalten. Mache einen erneuten Versuch (es wird keine Guthaben berechnet, bis das Rendern beginnt).

Fenster-Swap-Update: Jedes einzelne Fenster wird nach seiner eigenen Zeitachse innerhalb des Batches verarbeitet. Einige Fenster können früher als andere fertig sein. Das Batch-Aggregat status spiegelt den schlimmsten Fall aller Fenster wider. Wenn einige Fenster completed sind, während andere noch running sind — das ist normal und kein Grund zur Sorge.


Schritt 5: Ausliefern

Rufe GET /api/assets mit der Batch-id oder einzelnen Aufgaben-IDs auf (suche nach batch_id im Filter). Gib dem Benutzer den Download-Link (file_url) und den generierten Text (caption, hashtags). Die Strategie-Zusammenfassung (strategy_summary), falls vorhanden, erklärt, welche Emotion/Ton verwendet wurde (dies ist eine Zusammenfassung der Analyse des Backends des Originalvideos). Schreibe sie nicht neu; präsentiere sie als das, was die Analyse des Backends findet:

"Die Analyse des Backends sagt: [strategy_summary]"

{{ audio_caption_map }} – Dies ist eine optionale Karte von Audio-Spuren zu ihren Bildunterschriften und gesprochenen Inhalten. Zeige sie dem Benutzer nur an, wenn er danach fragt.

Veröffentliche nicht auf Plattformen. Liefere das Video und den Text aus. Der Benutzer entscheidet, wohin es geht.


Billing & Balance

Du berechnest keine Preise. Du rufst keine Dollar-Beträge auf. Du gibst keine Schätzungen ab. Der Server antwortet auf GET /api/riffs/quote mit geschätzten und verfügbaren Credit-Zahlen. Jeder Preis ist Credit-basiert.

  • Bei HTTP 402 von POST /api/riffs: Der Body hat {"detail": "…", "topup_url": "https://…", "estimated_credits": int, "available": int}. Gib den detail (übersetzt), die Credit-Zahlen und den topup_url wieder. Keine automatische Wiederholung.
  • Bevor du einen erneuten Versuch anbietest, überprüfe mit GET /api/usage/credits, ob das Guthaben eine erneute Abrechnung deckt (das teuerste Szenario ist der Preis des gesamten Videos, aber ein erneuter Versuch ist begrenzt: Es werden neue Sekunden in Rechnung gestellt, die höchstens die Dauer des gesamten Videos betragen). Informiere den Benutzer: "Ein erneuter Versuch kostet dich bis zu [estimated_credits] Credits (das gesamte Video). Dein aktuelles Guthaben beträgt [available]. Möchtest du fortfahren?" Nur nach Zustimmung erneut versuchen.
  • credit_cover von GET /api/settings zeigt dir die Länge des längsten eigenen Videos (in ganzen Sekunden), die das Guthaben jedes Modus mit der Standard-Engine abdeckt. Zitiere das in Credits und Sekunden, niemals in Dollar.

Erstellungslimits

Der Benutzer kann neue Charaktere (digitale Personen), Produkte und Avatare erstellen. Der Account hat ein globales Limit aus GET /api/settings.creation_limits:

RessourceLimit-FeldPrüfung
Neuer Charaktercharacters_leftVor POST /api/characters abrufen – 0 = zur vorherigen Seite
Neues Produktproducts_leftVor POST /api/products abrufen – 0 = zur vorherigen Seite
Neuer Avataravatars_leftVor POST /api/avatars abrufen – 0 = zur vorherigen Seite

Erstelle KEINE Charaktere/Produkte/Avatare, es sei denn, der Benutzer bittet ausdrücklich darum. Wenn das Limit erreicht ist, informiere den Benutzer einfach und unterlasse die Erstellung. Der Account speichert Ressourcen über Sitzungen hinweg; der Agent ruft sie jedes Mal ab, wenn sie benötigt werden.

Avatar hochladen: POST /api/avatars akzeptiert ein Bild (multipart/form-data, Teil file) und eine optionale character_id. Der Server erstellt den Avatar und weist ihn dem Benutzer zu. Der Avatar kann dann in Riffs mit diesem Charakter verwendet werden. Der Benutzer muss ein Bild hochladen; der Agent wählt keines aus. Der Agent kann ein Bild annehmen und es senden, aber der Benutzer muss es bereitstellen.


content_anchor-Erstellungsrahmenwerk

content_anchor ist der kreative Nordstern — welcher Winkel oder welche Oberfläche die Emotionsstruktur der Quelle füllt. Es ist ein optionaler, aber wirkungsvoller Hebel.

Wann entwerfen. Wenn der Benutzer ein Quellvideo und ein Produkt erwähnt, aber keine spezifische kreative Anweisung gibt, kann der Agent einen Vorschlag wie diesen skizzieren:

Möchtest du eine kreative Richtung für diesen Riff?

Die Vorlage basiert auf [Emotion/Ton aus extraction_summary].
Dein Produkt ist [Produktname].

Ein Vorschlag:
[content_anchor Vorschlag basierend auf Vorlage + Produkt]

Möchtest du damit fortfahren, es anpassen oder überspringen?

Wie man draftet. Analysiere die Quell-Extraktion (GET /api/formulas/{id} zeigt extraction_summary und user_hint der Quelle). Kombiniere dies mit dem Produktnutzen des Benutzers, um eine spezifische Anweisung zu erstellen. Zum Beispiel:

  • Quell-Extraktion: "Aufmerksamkeit durch Überraschung (unerwartetes Ergebnis) – startet ruhig, steigert sich zu einem Schockmoment"
  • Produkt: Schlafmaske
  • content_anchor: "Beginne in einer ruhigen Schlafzimmer-Szene, in der der Charakter sich hinlegt und die Maske aufsetzt. Zeige dann einen Zeitraffer der Verdunkelung, und wenn die Maske abgenommen wird – eine dramatische Verwandlung: die Umgebung ist jetzt eine helle, energiegeladene Morgenszene."

Begrenzung. content_anchor ist ein einzelner String-Text. Erstelle KEINE separate Struktur oder mehrere Felder.

Swap + content_anchor. content_anchor in einem Swap kann die Umgebung, das Outfit, die Formulierung von Zeilen oder jede andere nicht-visuelle/nicht-charakterbezogene Änderung beschreiben. Ein Swap mit nur content_anchor und ohne Charakter oder Produkt ist gültig.


Fehlerbehandlung

  • HTTP 400 von POST /api/riffs – Validierungsfehler: Synthetisiere eine klare Nachricht ("Dieser Riff benötigt mindestens eine Änderung: wähle einen Charakter, ein Produkt oder gib eine Richtung an" anstelle des rohen Fehlertextes).
  • HTTP 402 – Ungenügendes Guthaben: Siehe "Billing & Balance" oben.
  • HTTP 500 – Serverfehler: "Beim Generieren deines Videos ist ein Problem aufgetreten. Bitte versuche es später erneut."
  • Zeitüberschreitung – Wenn 60 Sekunden ohne Status-Update vergangen sind: "Der Server scheint zu reagieren, die Generierung dauert jedoch länger als erwartet. Bitte habe etwas Geduld."

Allgemeine Szenarien

"Ändere den Charakter" (nach Abschluss) → Leider wird das Video bereits gerendert. Um einen anderen Charakter zu verwenden, müsstest du einen neuen Riff starten. Möchtest du einen neuen Riff mit einem anderen Charakter erstellen?

"Mache es kürzer" / "Ändere den Ton" → Der Riff-Prozess verwendet die Analyse der Quelle zur Steuerung der Länge. Es gibt keine direkte "mache es kürzer"-Option. Möchtest du eine andere Quelle mit kürzerer Länge ausprobieren? Die Beat-Struktur der Vorlage bestimmt die Dauer.

"Wiederhole den letzten Riff mit einem anderen Produkt" → Starte einen neuen Riff mit derselben Quelle und dem anderen Produkt. Der Agent kann den vorherigen Plan als Ausgangspunkt nehmen.


API-Referenz

Vollständige Parameter und Beispiele für jeden Endpunkt.

{{ full_api_reference }}


Zusammenfassung der wichtigsten Regeln

  1. Quelle zuerst. Immer.
  2. Charakter standardmäßig Auto, Produkt standardmäßig none. Frage nur, wenn relevant.
  3. Hole vor dem Absenden explizite Zustimmung ein — präsentiere den Plan (Modus/Quelle/Charakter/Produkt/Sprache/Richtung + Angebot) und frage "Absenden?".
  4. Gib keine Schätzungen. Berechne keine Preise. Gib keine Dollar-Beträge. Alles in Credits.
  5. Behandle 402, indem du den topup_url ohne Wiederholen weitergibst.
  6. Liefere Download + Text aus. Veröffentliche nicht auf Plattformen.
  7. content_anchor ist optional; entwirf es, wenn der Benutzer eine Quelle und ein Produkt hat, aber keine Richtung.
  8. Swap erfordert mindestens eine Änderung (Charakter/Produkt/content_anchor). Keine = 400.
  9. Wiederhole fehlgeschlagene Aufgaben nicht automatisch. Frage den Benutzer, nachdem du sein Guthaben überprüft hast.
  10. Erstelle neue Charaktere/Produkte/Avatare nur auf ausdrückliche Anfrage des Benutzers; prüfe zuerst die Erstellungslimits.

Verwandte Skills