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:
| Endpunkt | Zweck |
|---|---|
GET /api/auth/me | Authentifizierungsstatus prüfen |
POST /api/skill/device/authorize · POST /api/skill/device/token | Ein-Klick-Anmeldung (Geräteautorisierung; kein Token-Einfügen) |
POST /api/riffs | Einmaliger Riff (der bevorzugte, nahezu einzige Generierungseinstieg) |
GET /api/formulas | Analysierte Vorlagen auflisten (eine der Quellen) |
GET /api/formulas/{id} | extraction_summary einer Vorlage (was extrahiert wurde) |
POST /api/formulas/analyze | Nur für Abonnenten – eine neue Quelle in deine eigene Vorlage analysieren ohne zu generieren (eine Bibliothek aufbauen) |
POST /api/formulas/{id}/refresh-analysis | Eine 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/characters | Digitale Charaktere (optionale Bindung) – Erstellung ist begrenzt, siehe "Erstellungslimits" |
GET /api/products · POST /api/products · POST /api/products/{id}/images | Produkte + Produktbilder (optionale Platzierung) – Erstellung ist begrenzt |
GET /api/settings | Bereitstellungsfä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/languages | Video-Sprachkandidaten |
GET /api/tasks/batch/{id} · GET /api/tasks/{id} | Fortschrittsabfrage |
GET /api/tasks · GET /api/tasks/stats | Aufgaben auflisten / zählen |
POST /api/tasks/{id}/cancel · POST /api/tasks/{id}/retry | Abbrechen / Wiederholen |
GET /api/assets | Fertige Videos abrufen (Video + Bildunterschrift + Hashtags) |
POST /api/pipeline/backfill · GET /api/pipeline/backfill/occupied | Zusätzliche Seitenverhältnisse zu einem bereits ausgelieferten Render hinzufügen (Reframe) / bereits erstellte Verhältnisse auflisten |
GET /api/usage/credits | Guthaben |
GET /api/billing/plans · GET /api/billing/subscription | Plan-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/quotefür einen Adapt- oder Swap-Riff (jede Quelle) undcredits_per_ratiovonGET /api/pipeline/backfill/occupiedfü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 – siehePOST /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/quotefür einen Adapt- oder Swap-Riff, siehe Schritt 3) und "Absenden?" fragen → bei BestätigungPOST /api/riffsaufrufen - Bei HTTP 402 dem Abschnitt "Abrechnung & Guthaben" folgen:
topup_urlwörtlich weitergeben, keine Wiederholung, kein stillschweigender Fehler GET /api/usage/creditsnur 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)
| Ebene | Rolle | Festgelegt durch | Freiheit |
|---|---|---|---|
| Formel + Grundgerüst | Boden-Garantie – ein validierter Emotionsmechanismus + Kamerasprache | Bei der Vorlagenanalyse | Keine (Ändern verliert den Wert des Riffs) |
| Charakter + Produkt | Basis-Konstanten – der digitale Mensch + Produktfakten | In den Einstellungen gewählt (oder Standard) | Unterschiedliche Auswahl = unterschiedliche Konstanten, aber innerhalb einer Aufgabe konstant |
| content_anchor | Decken-Treiber – welcher Verkaufsargument-Winkel, welche zu füllende Oberfläche | Agent + 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)
| Modus | mode | Was bleibt | Was ändert sich | Wähle ihn, wenn |
|---|---|---|---|---|
| Adapt (Standard) | adapt oder weggelassen | Die Emotionsformel: Hook, Rhythmus, Beats | Die Geschichte, Szenen, das Drehbuch, die Sprache | Der Benutzer sein eigenes Video möchte, das wie der Gewinner funktioniert |
| Swap | swap | Kamera, Schnitte, Bildausschnitt, Aktion, Timing, Ton und Bildformat der Quelle | Was 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 Zeile | Der 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 leerecontent_anchor. Keines der drei → 400, dessendetailein einfacher lokalisierter Satz ist (EN: "A swap needs at least one change: …"; der Body trägt keinen Fehlercode, also gibdetailweiter, 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 incontent_anchorgeä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_imageinGET /api/characters; rufe${BASE_URL}${reference_image}mit dem Session-Cookie ab, wie diefile_urleines 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 keinreference_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):
- 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 denencreator=="user"; der Benutzer kann sie umbenennen;extraction_summaryvon einer Vorlage zeigt die wichtigsten Beats;platform_templates=true,creator=="platform"sind plattformweit und nicht bearbeitbar). - TikTok-URL (
tiktok_url). Der Server lädt herunter, analysiert und generiert. - 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.
| Einstellung | Typ | Standard | Wie/wo man es bekommt |
|---|---|---|---|
character_ids | array of string | [] → Auto | GET /api/characters |
product_id | string oder null | null → kein Produkt | GET /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_visibility | enum | on_camera | Wird im Plan oder in /api/settings angezeigt; nur wenn product_id gesetzt ist sinnvoll |
language | enum | en | GET /api/languages |
content_anchor | string oder null | null | Vom Agenten entworfen, siehe Rahmenwerk unten |
user_hint | string oder null | null | Optionaler 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_ratio | string | "9:16" (hoch) | Nur für Adapt/Creation (Swap ignoriert sie: die Quelle bestimmt die Form). |
profile | string | "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 dendetail(übersetzt), die Credit-Zahlen und dentopup_urlwieder. 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_covervon 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:
| Ressource | Limit-Feld | Prüfung |
|---|---|---|
| Neuer Charakter | characters_left | Vor POST /api/characters abrufen – 0 = zur vorherigen Seite |
| Neues Produkt | products_left | Vor POST /api/products abrufen – 0 = zur vorherigen Seite |
| Neuer Avatar | avatars_left | Vor 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
- Quelle zuerst. Immer.
- Charakter standardmäßig Auto, Produkt standardmäßig none. Frage nur, wenn relevant.
- Hole vor dem Absenden explizite Zustimmung ein — präsentiere den Plan (Modus/Quelle/Charakter/Produkt/Sprache/Richtung + Angebot) und frage "Absenden?".
- Gib keine Schätzungen. Berechne keine Preise. Gib keine Dollar-Beträge. Alles in Credits.
- Behandle 402, indem du den topup_url ohne Wiederholen weitergibst.
- Liefere Download + Text aus. Veröffentliche nicht auf Plattformen.
content_anchorist optional; entwirf es, wenn der Benutzer eine Quelle und ein Produkt hat, aber keine Richtung.- Swap erfordert mindestens eine Änderung (Charakter/Produkt/content_anchor). Keine = 400.
- Wiederhole fehlgeschlagene Aufgaben nicht automatisch. Frage den Benutzer, nachdem du sein Guthaben überprüft hast.
- Erstelle neue Charaktere/Produkte/Avatare nur auf ausdrückliche Anfrage des Benutzers; prüfe zuerst die Erstellungslimits.