Tutorial
So rufen Sie seedance-2.5-flash Referenz-zu-Video über die HiAPI-API auf (curl + Python)
Funktionierende Anfragen, ein ausführbares Python-Skript und der Umgang mit dem Polling asynchroner Aufgaben
Auf dieser Seite
Was Referenz-zu-Video in der Praxis bedeutet
Referenz-zu-Video ist ein Generierungsmodus, bei dem Sie dem Modell zwei Dinge gleichzeitig geben: einen Text-Prompt, der Bewegung und Szene beschreibt, und ein oder mehrere Referenzmaterialien, die den Bildinhalt verankern. Der Prompt trägt die Absicht („langsames Heranfahren, die Figur dreht sich um und lächelt“), die Referenzmaterialien tragen Identität und Aussehen (eine Figur, ein Produkt, ein visueller Stil).
Der Modell-Endpunkt für diesen Workflow ist seedance-2.5-flash/reference-to-video, bereitgestellt über die einheitliche API von HiAPI. Sie senden model, prompt und Referenzmaterialien zusammen in einem einzigen Request-Body. Es gibt keinen separaten Upload-Schritt, den Sie orchestrieren müssten, und keine pro Material zu pflegende Registrierung.
Die praktische Konsequenz: Dies ist eine lang laufende Operation. Das Rendern eines kurzen Videos dauert immer noch deutlich länger als eine Textvervollständigung, daher behandelt die API den Aufruf als asynchrone Aufgabe. Ihre Anfrage erstellt die Aufgabe; ein zweiter Aufruf ruft deren Ergebnis ab. Diese Form „erst einreichen, dann pollen“ ist der wichtigste Punkt bei der Gestaltung und der Schwerpunkt, auf den sich der Rest dieses Tutorials aufbaut.
Alles im Folgenden bleibt innerhalb der HiAPI-Schnittstelle: eine Basis-URL, ein Authentifizierungs-Header, eine Endpunktfamilie.
Bevor Sie die erste Anfrage senden
Vor dem ersten Aufruf müssen drei Dinge vorbereitet sein.
1. API-Schlüssel
Erstellen Sie den Schlüssel in der HiAPI-Konsole und halten Sie ihn aus der Versionsverwaltung heraus. Die folgenden Beispiele lesen ihn aus einer Umgebungsvariablen:
export HIAPI_API_KEY="your_key_here"
Wenn Sie sich beim aktuellen Schlüsselformat oder den Header-Konventionen nicht sicher sind, prüfen Sie die API-Dokumentation der Plattform in der Konsole – raten Sie nicht und schreiben Sie den Schlüssel nicht hart in ein Skript, das Sie möglicherweise teilen.
2. Basis-URL und Authentifizierungs-Header
Alle Aufrufe gehen an die HiAPI-Basis-URL und tragen Ihren Schlüssel im Authorization-Header. Legen Sie sie einmal als Variable fest, damit jede Anfrage konsistent bleibt:
export HIAPI_BASE_URL="https://api.hiapi.ai"
Verwenden Sie die Basis-URL genau so, wie sie in der Dokumentation Ihres Kontos angegeben ist – ein nicht übereinstimmender abschließender Schrägstrich ist eine häufige Ursache für verwirrende 404-Fehler.
3. Modell-Endpunkt
Ihr Ziel ist seedance-2.5-flash/reference-to-video. Verweisen Sie im Request-Body mit dieser Kennung darauf, statt sie in den Pfad einzubetten, damit ein späterer Modellwechsel nur eine Zeile ändert.
Außerdem müssen Ihre Referenzmaterialien per URL erreichbar sein (oder in der vom Endpunkt dokumentierten Materialform vorliegen). Hosten Sie sie vor dem Start und machen Sie sie öffentlich zugänglich – eine defekte Referenz-URL ist die häufigste Ursache dafür, dass eine Aufgabe erfolgreich eingereicht wird, aber während der Generierung fehlschlägt.
Sobald diese drei Punkte eingerichtet sind, können Sie den Request-Body erstellen.
Den Request-Body mit Referenzmaterialien erstellen
Der Request-Body hat drei konzeptionelle Teile: welches Modell verwendet wird, was Sie wollen und worauf Sie sich beziehen.
Das Modell
Setzen Sie model auf seedance-2.5-flash/reference-to-video. Behandeln Sie es als gewöhnliches String-Feld – keine URL-Kodierung, kein Pfadsegment.
Der Prompt
Schreiben Sie den Prompt als Szenenbeschreibung, nicht als Wunschliste. Geben Sie Motiv, Aktion, Kamerabewegung und Tempo an. „Eine Person in roter Jacke geht auf die Kamera zu, halbnah, langsames Heranfahren, weiches Tageslicht“ liefert dem Modell viel mehr Informationen als „ein schönes Video einer Person“. Halten Sie den Prompt mit den gelieferten Referenzmaterialien konsistent: Wenn zwei Referenzmaterialien unterschiedliche Figuren zeigen, geben Sie an, welche maßgeblich ist.
Die Referenzmaterialien
Referenzmaterialien sind genau das, was diesen Endpunkt von einem gewöhnlichen Text-zu-Video-Aufruf unterscheidet. Sie übergeben ein oder mehrere Materialien, die definieren, was über die Frames hinweg konsistent bleiben soll. Praktische Regeln, die Iterationen sparen:
- Verwenden Sie die minimale Anzahl an Referenzmaterialien, die die Identität festlegt. Eine starke Referenz ist meist besser als vier mittelmäßige.
- Halten Sie die Referenzmaterialien untereinander konsistent. Widersprüchliche Blickwinkel oder Stile führen zu Drift in der Ausgabe.
- Bevorzugen Sie saubere, gut beleuchtete Quellen. Zugeschnittene, unscharfe oder stark gefilterte Referenzmaterialien übertragen diese Mängel.
- Prüfen Sie vor dem Einreichen, dass jede URL auflösbar ist – rufen Sie sie einmal selbst ab.
Wie die Referenzmaterialien im Request-Body genau verschlüsselt werden (Array-Feldname, Objektstruktur, unterstützte Materialtypen), sollte dem Anfrageschema des Endpunkts in der HiAPI-Dokumentation entnommen werden. Erstellen Sie den Request-Body nach diesem Schema, nicht aus dem Gedächtnis; das Schema ist die maßgebliche Quelle für Feldnamen, und nicht übereinstimmende Schlüssel führen zu stillem Scheitern.
Validieren Sie das JSON lokal, bevor die Anfrage das Netzwerk erreicht (python -m json.tool body.json). Ein fehlerhafter Body ist der am leichtesten zu findende Fehler und der ärgerlichste, wenn man ihn über einen Stacktrace debuggen muss.
Ein funktionierender curl-Aufruf
Der folgende Befehl folgt dem Muster „erst einreichen, dann pollen“: Er erstellt die Aufgabe und gibt die JSON-Antwort aus, die die Aufgabenkennung enthält, mit der Sie pollen werden.
curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash/reference-to-video",
"prompt": "Eine Person in roter Jacke geht auf die Kamera zu, halbnah, langsames Heranfahren, weiches Tageslicht",
"references": [
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/character-side.png"
]
}'
Ersetzen Sie die Referenz-URLs durch Ihre eigenen gehosteten Materialien und vergewissern Sie sich anhand der Modellseite in der HiAPI-Dokumentation, dass Endpunktpfad und Feldnamen stimmen, bevor Sie sich in der Produktion auf diesen Code verlassen – die Schema-Details sind maßgeblich, dieses Snippet dient nur der Veranschaulichung.
Worauf Sie in der Antwort achten sollten:
- Eine id (oder task/job-Kennung) – erfassen Sie sie; Sie benötigen sie bei jedem Polling.
- Ein status-Feld, das angibt, dass die Aufgabe angenommen wurde.
- Eventuelle Warnungen zu ignorierten oder abgelehnten Materialien.
Für bessere Lesbarkeit hübsch formatieren:
curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @body.json | python -m json.tool
Den Request-Body in body.json zu speichern, ist den kleinen Zusatzaufwand wert: Er lässt sich sauber versionieren, lesbar vergleichen und entfernt Shell-Quoting-Fehler aus dem Debugging-Bereich.
Derselbe Aufruf in Python
Hier ist der entsprechende Aufruf in Python, geschrieben so, dass er nach dem Setzen der Umgebungsvariablen direkt ausgeführt werden kann. Er verwendet nur die Standardbibliothek, sodass nichts installiert werden muss.
import json
import os
import urllib.request
BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
def submit_reference_video(prompt, references):
body = {
"model": "seedance-2.5-flash/reference-to-video",
"prompt": prompt,
"references": references,
}
req = urllib.request.Request(
f"{BASE_URL}/v1/videos/generations",
data=json.dumps(body).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(req, timeout=60) as resp:
payload = json.loads(resp.read().decode("utf-8"))
return payload
if __name__ == "__main__":
result = submit_reference_video(
prompt="Eine Person in roter Jacke geht auf die Kamera zu, halbnah, langsames Heranfahren, weiches Tageslicht",
references=[
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/character-side.png",
],
)
print(json.dumps(result, indent=2))
job_id = result.get("id")
print("job id:", job_id)
Zwei Details sind wichtiger, als sie scheinen. Erstens timeout=60 – der Einreichungsaufruf sollte schnell zurückkehren, aber eine hängende Verbindung ist schlimmer als ein schnelles Scheitern. Zweitens behandelt result.get("id") den Fall einer unerwarteten Antwortstruktur, statt in Ihrem normalen Pfad einen KeyError auszulösen.
Wenn Sie requests oder httpx bevorzugen, ist die Umstellung unkompliziert: gleiche URL, gleiche Header, gleicher JSON-Body. Das Erstellen des Bodys ist der Teil, den es zu übernehmen lohnt; der HTTP-Client ist austauschbar.
Eine asynchrone Aufgabe bis zum Abschluss pollen
Die Videogenerierung ist keine Anfrage, auf die Sie warten können. Sie reichen ein, erhalten die Kennung zurück und prüfen dann regelmäßig den Status, bis die Aufgabe einen Endzustand erreicht. Zwei Eigenschaften machen das sicher: Polling ist kostengünstig, und der Einreichungsaufruf hat die teure Arbeit bereits erledigt.
Die Schleife
import time
def wait_for_video(job_id, timeout_s=600, interval_s=5):
deadline = time.monotonic() + timeout_s
while time.monotonic() < deadline:
req = urllib.request.Request(
f"{BASE_URL}/v1/videos/generations/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
)
with urllib.request.urlopen(req, timeout=30) as resp:
job = json.loads(resp.read().decode("utf-8"))
status = job.get("status")
if status in ("succeeded", "completed"):
return job
if status in ("failed", "error", "cancelled"):
raise RuntimeError(f"job {job_id} ended with status {status}: {job.get('error')}")
time.sleep(interval_s)
raise TimeoutError(f"job {job_id} did not finish within {timeout_s}s")
Eine engere Schleife ist nicht schneller; sie verbraucht nur das Ratenlimit. Bei Videoaufgaben sind fünf Sekunden Intervall ein vernünftiger Standardwert.
Designhinweise
- Legen Sie immer eine Frist fest. Eine nie endende Aufgabe darf niemals einen Anfraget-Thread dauerhaft blockieren.
- Behandeln Sie unbekannte Zustände als „weiter warten“, nicht als Erfolg. Nur ein ausdrücklicher Erfolg ist ein Erfolg.
- Pollen Sie nicht innerhalb eines Web-Request-Handlers. Reichen Sie im Handler ein, geben Sie die Aufgaben-ID an den Client zurück und lassen Sie einen Hintergrund-Worker pollen und die Ergebnisse persistieren.
- Persistieren Sie Aufgaben-ID und Statusübergänge, damit ein unterbrochener Prozess fortgesetzt werden kann, statt erneut einzureichen und das Rendern doppelt zu bezahlen.
Diese Aufteilung in erst einreichen, dann pollen ist genau das, was es ermöglicht, eine langsame Video-Pipeline hinter einer schnellen API zu betreiben.
Häufige Fehler und wie man sie behebt
Nahezu jeder Fehler in der ersten Stunde fällt in eine von vier Kategorien. Prüfen Sie sie in dieser Reihenfolge.
1. Authentifizierung
Symptom: eine Unauthorized- oder Forbidden-Antwort, bevor überhaupt eine Aufgabe erstellt wurde.
Prüfen Sie: Ist HIAPI_API_KEY in der Shell oder im Prozess, der das Skript ausführt, tatsächlich gesetzt? Ist der Header genau Authorization: Bearer <key>? Laden Sie den Schlüssel beim Import, während das Skript ihn später erwartet? Geben Sie die ersten Zeichen des aufgelösten Schlüssels aus (niemals den gesamten Schlüssel) und vergewissern Sie sich, dass er kein leerer String ist.
2. Endpunktpfad
Symptom: Nicht gefunden, meist sofort.
Prüfen Sie: genau ein Schrägstrich zwischen Basis-URL und Pfad – deshalb ruft das Python-Beispiel .rstrip("/") auf. Vergewissern Sie sich anhand der Modellseite in der Dokumentation, dass der Generierungspfad und der Polling-Pfad stimmen; eine Polling-URL ohne das Aufgaben-ID-Segment liefert jedes Mal 404. Ein abschließender Schrägstrich, den der Server nicht erwartet, erzeugt dasselbe Symptom.
3. Fehlerhafter Request-Body
Symptom: ein Validierungsfehler oder eine Aufgabe, die direkt nach der Annahme fehlschlägt.
Prüfen Sie: Führen Sie json.dumps(body) aus und prüfen Sie die Ausgabe. Stimmt model exakt mit seedance-2.5-flash/reference-to-video überein? Ist das Referenzfeld ein Array, und ist jeder Eintrag eine im Browser auflösbare String-URL? Senden Sie Content-Type: application/json? Lassen Sie den Body durch python -m json.tool laufen, um Syntaxfehler auszuschließen, bevor sie das Netzwerk erreichen.
4. Aufgabenstatus
Symptom: Der Einreichungsaufruf ist erfolgreich, aber die Aufgabe schlägt fehl oder wird nie abgeschlossen.
Prüfen Sie: Lesen Sie das Fehlerfeld in der Statusantwort – es gibt meist die Ursache an, am häufigsten ein nicht erreichbares oder nicht unterstütztes Referenzmaterial. Wenn die Aufgabe einfach stehen bleibt, vergewissern Sie sich, dass Sie die richtige ID pollen und dass der Statusvergleich Ihrer Schleife die Endzustände abdeckt, die die API tatsächlich zurückgibt. Protokollieren Sie jeden Statusübergang; der letzte Status vor dem Fehler ist Ihre Diagnosegrundlage.
Eine Regel, die alle vier Fehlersuchen verkürzt: Protokollieren Sie bei jedem Aufruf die Request-ID und die Aufgaben-ID. Im Fehlerfall verwandelt eine ID einen vagen Fehlerbericht in eine konkrete Nachschlagemöglichkeit.
Nächste Schritte
Sie kennen jetzt die vollständige Form: den Request-Body mit Prompt und Referenzmaterialien erstellen, ihn einreichen, bis zum Endzustand pollen und die vier häufigen Fehlerklassen behandeln. Von hier aus sind die nächsten natürlichen Schritte eher auf der Engineering-Ebene als auf der API-Ebene.
- Umhüllen Sie die Einreichung mit Wiederholungen und Backoff für vorübergehende Netzwerkfehler, aber wiederholen Sie niemals eine Aufgabe, die bereits eine ID hat – das wäre ein doppeltes Rendern.
- Verlagern Sie das Polling in einen Worker oder eine Queue, damit die HTTP-Schicht reaktionsfähig bleibt und Aufgaben einen Prozessneustart überleben.
- Speichern Sie die Aufgaben-ID zusammen mit Ihren eigenen Anfrage-Metadaten (Prompt, Referenzmaterialien, anfragender Benutzer), damit Ergebnisse auch Monate später nachvollziehbar sind.
- Geben Sie Referenzmaterialien erst nach der Validierung frei – rufen Sie jede URL ab, die ein Benutzer bereitstellt, bevor Sie eine Aufgabe dafür ausgeben.
Das maßgebliche Anfrageschema, die unterstützten Materialformen und aktuelle Endpunktdetails finden Sie auf der Modellseite für seedance-2.5-flash Referenz-zu-Video auf HiAPI. Bauen Sie auf diesem Schema auf und halten Sie die Aufteilung in erst einreichen, dann pollen ein, dann bleibt die Integration unspektakulär – genau das wünscht man sich von einer Video-Pipeline.
Ähnliche Artikel
Alle Artikel ansehen →-
Tutorial
gpt-6.2-sol Praxisleitfaden: 5 hochwertige Einsatzszenarien für Textmodelle im Geschäftsalltag
-
Tutorial
gpt-6.2-astra Praxisleitfaden: Integration und Umsetzung von 5 hochwertigen Text-Szenarien
Eine Entwickler-Checkliste von der Szenarioauswahl bis zur technischen Umsetzung
-
Tutorial
Tripo H3.1 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Umsetzungshinweise
Von Text-zu-3D bis Multi-View-Rekonstruktion: den richtigen Modus und die richtigen Parameter je nach Geschäftsszenario wählen