RunningHub Seedance 2.0 API-Setup: Schlüssel, Assets und erster Aufruf

AI Overview

Was ist der schnellste Weg, die RunningHub Seedance 2.0 API einzurichten?

Erstellen Sie einen RunningHub-API-Schlüssel, wählen Sie die genaue Seedance 2.0-KI-Anwendung oder Modellroute aus, senden Sie eine minimale Anfrage und fragen Sie anschließend deren taskId ab. Fügen Sie Uploads, Webhooks und Produktions-Retries erst hinzu, nachdem dieser erste Aufruf erfolgreich war.

Sollte ich den AI App API oder einen ComfyUI-Workflow verwenden?

Verwenden Sie den AI App API, wenn Sie einen festen, gehosteten Eingabevertrag benötigen. Nutzen Sie die ComfyUI-OpenAPI-Route, wenn Ihr Team sichtbare Knotenzuordnungen, wiederverwendbare Graphen, Asset-Vorbereitung oder Modellschritte benötigt, die sich zwischen Projekten ändern.

Wie funktionieren Seedance 2.0-Asset-IDs in RunningHub?

Asset-IDs ermöglichen es unterstützten Seedance 2.0-Knoten, vorbereitete Referenzen wiederzuverwenden. Die ComfyUI-Integration akzeptiert einfache IDs, Werte im Format asset://, durch Kommas getrennte Listen oder einen JSON-Array-String – doch der gewählte Knoten bestimmt weiterhin die zulässigen Eingabeslots.

Warum muss eine URL für einen abgeschlossenen Task sofort kopiert werden?

RunningHub dokumentiert temporäre Medienlinks für Uploads und generierte Ergebnisse. Verschieben Sie jedes genehmigte MP4-Video und jedes Poster unverzüglich nach erfolgreichem Abschluss des Tasks in Ihren eigenen dauerhaften Speicher; eine gespeicherte Task-ID ist kein permanentes Medienarchiv.

Was Sie vor Ihrem ersten Aufruf benötigen

Ein zuverlässiger Setup beginnt mit vier bekannten Werten: der API-Region, einem gültigen Schlüssel, der exakten KI-Anwendungs- oder Modellkennung sowie einem Speicherziel, das Sie kontrollieren. Kopieren Sie keinen Endpunkt aus einem nicht verwandten Tutorial und gehen Sie davon aus, dass dessen Anfrageinhalt kompatibel ist. RunningHub stellt mehrere Aufrufstile bereit, und jede veröffentlichte API-Detailseite ist der verbindliche Vertrag für diese Route. Der umfassendere Seedance 2.0-API-Leitfaden erläutert das allgemeine asynchrone Muster; dieser Leitfaden konzentriert sich ausschließlich auf RunningHub.

Halten Sie den Schlüssel außerhalb der Versionskontrolle. Für die offizielle ComfyUI-Integration lautet das dokumentierte Umgebungsmuster:

export RH_API_BASE_URL="https://www.runninghub.cn/openapi/v2"
export RH_API_KEY="replace-with-your-key"

Verwenden Sie die regionale Basis-URL, die in Ihrer eigenen RunningHub-Konsole und in der aktuellen Dokumentation angezeigt wird. Ein Consumer-Key kann eine berechtigte Mitgliedschaft erfordern, während Enterprise-Keys andere Zugriffsregeln aufweisen können. Behandeln Sie die Möglichkeit, ein Modell im Katalog anzuzeigen, und die Möglichkeit, es mit Ihrem Schlüssel aufzurufen, als zwei voneinander unabhängige Prüfungen.

Bevor Sie Credits verbrauchen, definieren Sie einen Akzeptanz-Testfall: ein Subjekt, eine Aktion, eine Kamerabewegung, eine Dauer und ein Ausgabeverhältnis. Testen Sie das kreative Briefing zunächst im Seedance 2.0-Modell-Arbeitsbereich, falls Sie unsicher sind, ob die Prompt selbst funktionsfähig ist. Dadurch trennen Sie Prompt-Probleme von Integrationsproblemen.

Verwenden Sie für den ersten Aufruf einen visuell einfachen Akzeptanzrahmen. Dieses frische Produktbild macht Silhouette, Reflexionen, Wasserbewegung und Hintergrundstabilität leicht prüfbar; es ist kein offizieller RunningHub-Benchmark.

Wählen Sie die richtige RunningHub-Route

RunningHub bietet zwei praktikable Wege für diese Aufgabe. Die KI-Anwendungsroute ist nützlich, wenn der Anbieter Seedance 2.0 bereits in einer stabilen Anwendung mit benannten Eingaben verpackt hat. Sie senden an diese App-ID und erhalten eine taskId. Das ComfyUI-OpenAPI-Plugin ist besser geeignet, wenn der Graph selbst Teil Ihrer Produktionslogik ist oder wenn Sie dessen Seedance 2.0-Asset-Hilfsfunktionen benötigen.

Kombinieren Sie die Routen nicht in Ihrem ersten Test. Eine minimale KI-Anwendungsanfrage sollte Authentifizierung, App-Kennung, Warteschlangeneinreichung und Ergebnisabruf beweisen. Ein minimaler ComfyUI-Aufruf sollte beweisen, dass der exportierte Workflow unverändert läuft, bevor Sie dynamische nodeInfoList-Überschreibungen einführen.

Das offizielle RunningHub ComfyUI-Plugin kann Konfigurationen aus einem Einstellungsknoten, Umgebungsvariablen oder einer .env-Datei lesen, wobei Knoteneinstellungen Vorrang haben. Notieren Sie, welche Ebene den Schlüssel bereitgestellt hat. Andernfalls könnte ein Teamkollege das Umgeheimnis rotieren, während ein alter Knotenwert stillschweigend weiterhin Priorität behält.

Eine referenzreiche Szene sollte Person, Garderobe, Tier, Wetter und Ort lesbar halten. Das Bild ist eine frische, illustrative Ausgabe, kein offizieller Modellvergleich.

Schritt-für-Schritt-Setup der RunningHub Seedance 2.0 API

Beginnen Sie mit einem Anfrage-Gerüst, das ausschließlich Variablen enthält, die tatsächlich Ihrem Dienst gehören. Die aktuelle KI-Anwendungs-Dokumentation von RunningHub zeigt einen Endpunkt im Format /run/ai-app/{appId} und gibt ein Task-Objekt mit Status wie QUEUED, RUNNING, SUCCESS oder FAILED zurück. Nutzen Sie das Anfragebeispiel, das auf der exakten API-Detailseite generiert wird, als maßgebliche Quelle für Feldnamen.

const response = await fetch(`${RUNNINGHUB_BASE}/run/ai-app/${APP_ID}`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RH_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    nodeInfoList: inputMappings,
    webhookUrl: process.env.RH_WEBHOOK_URL
  })
});

if (!response.ok) throw new Error(`Submit failed: ${response.status}`);
const task = await response.json();
```Für einen ComfyUI-Workflow importieren Sie eines der passenden Beispiele, verbinden Sie `RH OpenAPI Settings` nur dann, wenn Sie keine Umgebungskonfiguration verwenden, und führen Sie den Graphen mit statischen Werten aus. Sobald er funktioniert, machen Sie ausschließlich die Knoten verfügbar, deren Werte variieren müssen – also Prompt, Referenz, Dauer, Seitenverhältnis oder Ausgabeoptionen – und speichern Sie diese Knoten-IDs neben der Workflow-Version.

Die Seedance 2.0-Asset-Tools von RunningHub bieten eine weitere Option. Bei `real_person_mode=false` wird der Direkt-Upload-Pfad gewählt. Wenn aktiviert, können ausgewählte lokale Bild- oder Videofelder vor der Modellanfrage in Assets konvertiert werden. `conversion_slots` steuert, welche Felder daran teilnehmen. Testen Sie zunächst ein einzelnes Bild, da bei einer Nutzlast aus neun Bildern und drei Videos nicht ersichtlich ist, welches Mapping zum Fehler geführt hat.

```official-video
src=https://r2.seedance.tv/blog/gpt-image-2-5-to-video-workflow/product-orbit-motion-v1.mp4
poster=https://r2.seedance.tv/blog/gpt-image-2-5-to-video-workflow/product-orbit-motion-poster-v1.jpg
label=Vertikales Produkt-Orbit-Video zur Überprüfung eines abgerufenen API-Ergebnisses

Diese abspielbare Seedance-Bewegungsausgabe zeigt, worauf nach dem Abruf zu achten ist: stabile Produktgeometrie, kontrollierte Kamerabewegung und saubere Einzelbilder. Sie wird nicht als RunningHub-Benchmark präsentiert.

Erstellen Sie Eingaben, die die API-Grenze überstehen

Die API kann nicht ableiten, welche Datei der erste Frame, der letzte Frame, eine Charakterreferenz oder eine Stilreferenz ist. Erstellen Sie daher vor der Übergabe ein Eingabemanifest. Speichern Sie darin einen lokalen Namen, die Quell-Prüfsumme, den MIME-Typ, den vorgesehenen Slot, ggf. die Asset-ID und die Prompt-Bezeichnung, die sich darauf bezieht. Das ist nützlicher als ein Ordner mit Dateien namens final-2.png.

{
  "shot": "kitchen-01",
  "references": [
    {"role": "first_frame", "assetId": "asset-example-01"},
    {"role": "style", "url": "https://your-storage.example/style.jpg"}
  ],
  "prompt": "Mittlere Tracking-Aufnahme; Koch platziert das Gericht; Dampf steigt auf; warmes praktisches Licht",
  "ratio": "16:9"
}

Die dokumentierte ComfyUI-Integration akzeptiert eine einzige Asset-ID, einen Wert im Format asset://<asset_ID>, durch Komma oder Zeilenumbruch getrennte Werte oder eine JSON-Array-Zeichenkette. Diese Flexibilität ist praktisch, doch Konsistenz ist sicherer: Wählen Sie in Ihrem Codebase eine Darstellungsform aus und validieren Sie sie vor Ausführung des Graphen. Bei Image-to-Video identifiziert die Integration first_frame und last_frame; multimodale Video-Knoten können mehrere Bild- und Videofelder bereitstellen. Nutzen Sie den Referenz-zu-Video-Arbeitsbereich, um ein Referenzpaket zu verfeinern, bevor Sie es automatisieren.

Formulieren Sie Prompts als ausführbare Aufnahmeanweisungen. Trennen Sie Bildausschnitt, Motiv, Aktion, Umgebung, Licht und Ton. Falls der erste Aufruf kreativ fehlschlägt, vereinfachen Sie stattdessen nur einen Aspekt – statt gleichzeitig Endpunkt, Assets, Prompt und Workflow zu ändern. Der Image-to-Video-Prompt-Workflow bietet ein wiederverwendbares Prompt-Muster.

Dieses frische, fertige Einzelbild demonstriert einen Test mit lesbarer Handstellung, klarer Speisen-Geometrie, sichtbarem Dampf und natürlichem Licht – vier Details, die über den gesamten generierten Clip hinweg geprüft werden sollten.

Abfragen, Speichern und Überprüfen des Ergebnisses

Nach der Übermittlung speichern Sie die zurückgegebene taskId unverzüglich, bevor Sie mit der Polling-Schleife beginnen. Verwenden Sie exponentielles Backoff mit Obergrenze, brechen Sie bei endgültigem Fehler ab und gestalten Sie das Polling idempotent, sodass ein neu gestarteter Worker dieselbe Aufgabe fortsetzen kann. Falls Ihr Endpunkt Webhooks unterstützt, überprüfen Sie dessen Signatur oder gemeinsames Geheimnis, bevor Sie die Nutzlast als vertrauenswürdig betrachten. Der Callback sollte den bestehenden Aufgaben-Eintrag aktualisieren – nicht eine zweite Generierung erstellen.

Im Erfolgsfall (SUCCESS) kopieren Sie die MP4-Datei sofort. RunningHub weist darauf hin, dass generierte Ergebnislinks und Upload-Links nach 24 Stunden ablaufen können. Daher ist es unsicher, die Datei erst herunterzuladen, wenn ein Mensch eine Prüfungsansicht öffnet. Speichern Sie stattdessen Datei, Prüfsumme, Anbieter-Aufgaben-ID, Prompt-Version, Quell-Manifest und Generierungszeitstempel zusammen. Erstellen Sie erst dann ein Poster und einen für Browser abspielbaren Proxy – und nur, falls Ihr Delivery-Stack diese benötigt.

Coffee-and-Steam-Bewegungsclip zur Überprüfung subtiler Bewegung

Diese zweite reale Bewegungsausgabe nutzt zurückhaltende Handbewegung, aufsteigenden Dampf und Sonnenlicht und bietet Rezensenten damit eine andere Fehleroberfläche als das Produkt-Orbit.

Überprüfen Sie den gesamten Clip – nicht nur dessen ersten Frame. Bewerten Sie Identität, Objektgeometrie, Bewegungskontinuität, Kamerapfad, Hintergrundstabilität, Audio-Passgenauigkeit und Lieferungssicherheit. Eine technisch erfolgreiche Aufgabe kann dennoch unbrauchbar sein. Für Kampagnen mit mehreren Modellen oder Anbietern zeigt der Multi-Modell-AI-Video-Workflow, wie Sie einen einheitlichen Prüfstandard über alle Routen hinweg bewahren.

Richtung des Stoffes, Handform, Fußkontakt, Horizontstabilität und Kamerahöhe bilden eine kompakte Akzeptanz-Checkliste für ein bewegungsintensives Ergebnis.

Beheben Sie häufige RunningHub-Seedance 2.0-API-Fehler

Behandeln Sie Fehler nach Lebenszyklusphase. Ein 401- oder 403-Fehler deutet auf Schlüssel, Region, Mitgliedschaft oder Berechtigung – nicht auf das Prompt – hin. Eine Ablehnung der Anfrage vor Erhalt einer taskId bedeutet meist, dass Endpunkt, App-ID, Inhaltstyp oder Struktur des Anfragetexts falsch sind. Eine Aufgabe, die in der Warteschlange hängt, ohne Fortschritt zu machen, weist auf ein Warteschlangen- oder Timeout-Problem hin. Eine FAILED-Aufgabe mit Angaben zur Inhaltsüberprüfung erfordert ein sichereres Prompt oder eine sicherere Referenz. Eine erfolgreich abgeschlossene Aufgabe mit abgelaufenem URL weist auf einen Speicherfehler hin.| Symptom | Zuerst prüfen | Korrekturmaßnahme | |---|---|---| | Nicht autorisiert | Schlüsselquelle und Basisregion | Veraltete Knoten-Überschreibung entfernen; Schlüssel rotieren und einen minimalen Aufruf erneut testen | | Ungültige Knotenzuordnung | Workflow-Version und Knoten-IDs | Aktuellen Graphen exportieren und nur die benannten Knoten aktualisieren | | Asset-Konvertierung schlägt fehl | Slot-Name, -Typ und Zugriff auf die Quelle | Einen Slot testen; als Fallback die dokumentierte Direkt-Upload-Methode verwenden | | Aufgabe bleibt in der Warteschlange | Abrufintervall und Kontowarteschlange | Zurückziehen („back off“); keine doppelten Jobs automatisch erstellen | | Ergebnis-URL abgelaufen | Ereignis im dauerhaften Speicher | Nur erneut ausführen, falls die ursprüngliche Datei niemals kopiert wurde | | Clip ist visuell fehlerhaft | Prompt und Quell-Manifest | API unverändert belassen und nur eine kreative Variable anpassen |

Protokollieren Sie den Statuscode, den Anbieter-Fehlercode, die Task-ID, die Workflow-Version und die bereinigten Feldnamen. Niemals den API-Schlüssel oder vollständige private Medien-URLs protokollieren. Fügen Sie in Ihrem eigenen Dienst einen Idempotenzschlüssel hinzu – auch wenn die Anbieter-Routine keinen solchen Schlüssel bereitstellt; dies verhindert, dass ein Client-Retry zu einer doppelten Abrechnung führt.

Falls die Integration technisch funktioniert, aber die Koordination zum Engpass wird, nutzen Sie Seedance Agent, um Referenzen zu organisieren, ein Kurzkonzept in Shots umzuwandeln, genehmigte Ergebnisse zu vergleichen und ausschließlich die fehlgeschlagene Stufe erneut auszuführen. Dies ist eine Entscheidung auf Produktionsebene – kein Ersatz für das Verständnis der zugrundeliegenden API.

Fazit

Eine robuste RunningHub Seedance 2.0 API-Integration ist ein Lebenszyklus – kein einzelner erfolgreicher cURL-Befehl: Wählen Sie die richtige AI-App oder die passende ComfyUI-Route, lagern Sie den Schlüssel aus dem Code aus, validieren Sie einen minimalen Aufruf, ordnen Sie Assets explizit zu, speichern Sie das taskId dauerhaft, warten Sie beim Polling ab („back off“), kopieren Sie temporäre Ergebnisse unverzüglich und bewerten Sie den gesamten Clip anhand einer schriftlichen Abnahmeliste. Sobald diese Grenzen stabil sind, können Webhooks, breitere multimodale Eingaben, Batch-Terminplanung und manuelle Freigabe hinzugefügt werden – ohne Fehler hinter zusätzlicher Automatisierung zu verbergen. Um Referenzen und Shots zu planen, bevor Budget eingesetzt wird – und genehmigte Arbeit durch Review und gezielte Neuausführungen zu führen – starten Sie das Projekt mit Seedance Agent.