Blog

Tutorial

So verwenden Sie topaz-upscale/video über die HiAPI API: curl- und Python-Beispiele

Nov 17, 2026
Titelbild: Mehrere halbtransparente Glasplättchen überlappen sich in zurückhaltenden Winkeln und brechen auf hellem Hintergrund kühle blaue Parallelfarbbänder; das Bild enthält keinen Text.
Auf dieser Seite

Was topaz-upscale/video leistet und wann es passt

topaz-upscale/video ist der Video-Verbesserungs-Endpoint auf HiAPI. Sie senden ihm ein Quellvideo und eine Anweisung, und er gibt das verbesserte Video zurück: höhere Auflösung, rekonstruierte feine Details und optional flüssigere Bewegung durch Frame-Interpolation. Greifen Sie zu diesem Endpoint, wenn das Material bereits existiert und das Problem in der Qualität liegt, nicht in der Inhaltserzeugung.

Typische Einsatzszenarien

Aufgaben, die natürlicherweise zu diesem Endpoint passen:

  • Archiv- und Altmaterial – alte Aufnahmen, komprimierte Bildschirmaufnahmen oder übernommene Medien, die in moderner Auflösung vorzeigbar aussehen sollen.
  • Rendering-Pipelines – fertige Sequenzen, die zur Geschwindigkeit zunächst in niedrigerer Auflösung gerendert wurden und anschließend für die Auslieferung verbessert werden.
  • Bewegungsbereinigung – Quellen mit niedriger Bildrate benötigen interpolierte Frames, um Ruckeln bei der Wiedergabe zu vermeiden.
  • Auslieferungsvarianten – ein Master, mehrere Ausgabestufen, wobei die Verbesserung je Stufe angewendet wird.

Wann es statt Alternativen gewählt werden sollte

Die Entscheidung läuft meist auf drei Fragen hinaus:

  1. Liegt das Problem in Auflösung und Detail oder im Inhalt? Wenn Sie neue Pixel erfinden müssen (Szenen, die nie gefilmt wurden), ist dies das falsche Werkzeug. Verbesserung setzt echte Quellframes voraus.
  2. Kann Ihre Pipeline asynchrone Arbeit tolerieren? Videoaufgaben sind nicht sofort erledigt. Wenn Ihre Benutzererfahrung Reaktionen im Subsekundenbereich verlangt, gehört dieser Endpoint in einen Hintergrundjob, nicht in den Request-Handler.
  3. Brauchen Sie Frame-Interpolation und Upscaling? Wenn Bewegungsharmonie wichtig ist, wünschen Sie beides in einem Durchgang statt mehrerer separater Werkzeuge hintereinander. topaz-upscale/video deckt beides ab.

Wenn Ihre Quelle ein einzelnes Standbild ist, verwenden Sie stattdessen den Bild-Upscaler. Wenn die Quelle selbst in Ordnung ist, aber schlecht kodiert wurde, beheben Sie zuerst die Kodierung – die Verbesserung kann Details, die durch starke Kompression bereits zerstört wurden, nicht zurückholen, und Sie zahlen für Rechenzeit ohne Qualitätsgewinn.

Die Anfrage vor dem ersten Aufruf vorbereiten

Die meisten Fehler beim ersten Aufruf stammen von fehlenden Voraussetzungen, nicht von schlechten Prompts. Stellen Sie diese vor dem Schreiben von Code bereit.

Konto und Zugangsdaten

Sie benötigen einen HiAPI-API-Schlüssel mit Zugriff auf topaz-upscale/video. Bewahren Sie den Schlüssel in einer Umgebungsvariable statt im Quellcode auf – jedes folgende Beispiel liest HIAPI_API_KEY aus der Umgebung.

export HIAPI_API_KEY="your-key-here"

Erreichbares Quellmedium

Das Modell muss Ihre Eingabe abrufen können. Zwei zuverlässige Wege:

  • Öffentliche oder signierte URL – eine URL, die der Dienst ohne interaktive Authentifizierung herunterladen kann. Wenn Ihr Speicher signierte Links benötigt, erzeugen Sie einen Link mit großzügiger Gültigkeitsdauer und denken Sie daran, ihn bei Wiederholungen neu zu erzeugen, sonst scheitern lange Aufgaben mittendrin.
  • Zuerst hochladen – laden Sie die Datei über den Upload-Mechanismus der Plattform hoch und referenzieren Sie die zurückgegebene Kennung. Für große Dateien und alles hinter privaten Netzen ist dies die sicherere Wahl.

Merkmale der Quelle, die geprüft werden sollten

Bevor Sie einen Aufruf verbrauchen, bestätigen Sie:

  • Dauer. Lange Videos bedeuten lange Aufgaben. Wenn Sie testen, schneiden Sie einen 5–10-Sekunden-Ausschnitt aus der Mitte der Quelle – die Mitte ist meist repräsentativer als die Anfangsframes.
  • Codec und Container. Seltene Codecs lassen sich manchmal nicht dekodieren. Im Zweifel in einen gängigen Container neu verpacken.
  • Bildrate. Genaue erfassen; sie wird bei der Frame-Interpolation benötigt.
  • Auflösung. Notieren Sie die exakten Quellabmessungen, damit Ihr Vorher-Nachher-Vergleich ehrlich bleibt.

Ausgabeziel festlegen

Legen Sie Ausgabeauflösung und Bildrate vor dem ersten Aufruf fest, nicht danach. Einstellungen, die für ein 720p-Quelle zu 1080p sinnvoll sind, unterscheiden sich von denen für 480p zu 4K. Schreiben Sie das Ziel auf; Sie werden es in jeder folgenden Anfrage wiederverwenden.

Aufruf mit curl ausführen

Die Anfrage ist ein POST mit JSON-Body an den topaz-upscale/video-Endpoint. Hier ein vollständig lauffähiges Beispiel – ersetzen Sie es durch Ihre eigenen Medien-URLs.

curl -sS https://api.hiapi.ai/v1/video/enhance \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "topaz-upscale/video",
    "input": {
      "video": "https://your-bucket.example.com/clips/source_720p.mp4"
    },
    "parameters": {
      "target_resolution": "1080p",
      "target_fps": 60,
      "interpolation": "smooth",
      "detail": "balanced"
    },
    "prompt": "Feine Texturen auf Stoffen und Haut wiederherstellen, Körnung natürlich halten, auf 60fps interpolieren ohne Geisterbilder"
  }'

Die Antwort interpretieren

Die unmittelbare Antwort bestätigt die Aufgabe. Sie erhalten eine Aufgabenkennung und ein Statusfeld. Videoarbeit ist asynchron, daher lautet das tatsächliche Muster:

# 1. Absenden und Aufgaben-ID erfassen
JOB_ID=$(curl -sS https://api.hiapi.ai/v1/video/enhance \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | jq -r '.id')

# 2. Abfragen bis der Status terminal ist
curl -sS "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .output'

Beim Lesen des Ergebnisses sind drei Felder wichtig:

  • status – von der Warteschlange über laufend bis terminal. Behandeln Sie jeden nicht erkannten Status als „weiter warten“, nicht als Erfolg.
  • output – bei Erfolg vorhanden, enthält die URL oder Kennung des verbesserten Videos.
  • error – bei Fehler vorhanden. Lesen Sie die Meldung wörtlich; sie nennt meist das problematische Feld.

Wenn Sie Prompts iterieren, legen Sie den Anfrage-Body in eine Datei (request.json) und verwenden Sie -d @request.json. Das hält die Shell-Historie sauber und erlaubt es Ihnen, verschiedene Versionen derselben Anfrage zu diffen.

Denselben Endpoint aus Python aufrufen

Die Python-Version ist ein dünner Wrapper um denselben HTTP-Vertrag. Verwenden Sie requests, halten Sie den Schlüssel in der Umgebung und verpacken Sie Absenden und Abfrageschleife in Funktionen, sodass Aufrufer nicht wissen müssen, dass es asynchron ist.

import os
import time
import requests

BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

def enhance_video(
    video_url: str,
    prompt: str,
    target_resolution: str = "1080p",
    target_fps: int = 60,
    poll_interval: float = 5.0,
    timeout: float = 1800.0,
) -> str:
    payload = {
        "model": "topaz-upscale/video",
        "input": {"video": video_url},
        "parameters": {
            "target_resolution": target_resolution,
            "target_fps": target_fps,
            "interpolation": "smooth",
            "detail": "balanced",
        },
        "prompt": prompt,
    }

    resp = requests.post(f"{BASE}/video/enhance",
                         headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    job_id = resp.json()["id"]

    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        if data["status"] == "succeeded":
            return data["output"]["video"]
        if data["status"] == "failed":
            raise RuntimeError(data.get("error", "Verbesserung fehlgeschlagen"))
        time.sleep(poll_interval)

    raise TimeoutError(f"Aufgabe {job_id} wurde nicht innerhalb der erwarteten Zeit abgeschlossen")

Hinweise zur Verwendung in einer echten Pipeline

  • Exponentielles Backoff beim Abfragen. Ein festes Intervall von fünf Sekunden ist für Shell-Skripte in Ordnung; in der Produktion sollten Sie Backoff mit Obergrenze verwenden. Lange Videos brauchen eine Weile, und häufigeres Abfragen macht sie nicht schneller fertig.
  • Idempotenz. Wenn der Absendeaufruf in ein Timeout läuft, wissen Sie möglicherweise nicht, ob die Aufgabe gestartet wurde. Protokollieren Sie den Anfrage-Body zusammen mit der Aufgaben-ID, um Duplikate abzugleichen, statt blind erneut zu senden.
  • Aufgaben-ID persistieren. Schreiben Sie sie sofort nach Erhalt in die Datenbank. Wenn der Prozess während des Abfragens stirbt, können Sie anhand der ID fortsetzen, statt für eine zweite Verbesserung zu zahlen.

Prompt-Rezepte für Frame-Interpolation

Frame-Interpolation ist der Bereich, in dem Prompts am häufigsten schiefgehen – entweder zu vage, um irgendetwas zu steuern, oder zu präskriptiv, sodass das Modell widersprüchliche Ziele verfolgt. Prompts bestehen neben strukturierten Parametern; lassen Sie die Formulierung Absicht und Bewegungscharakter beschreiben und die Parameter die numerischen Ziele tragen.

Muster: Bewegung beschreiben, nicht Mathematik

Schlechter:

interpolate

Besser:

Auf flüssige 60fps interpolieren. Originalen Bewegungsrhythmus beibehalten – Geschwindigkeit nicht verändern. Schwenks und Kamerabewegungen sollen linear und stabil sein; Verzerrungen an Frame-Rändern vermeiden.

Sie haben der API die Zielbildrate bereits in parameters mitgeteilt. Der Prompt sollte beschreiben, wie flüssige Bewegung für dieses Material aussieht.

Muster: Artefakte benennen, die vermieden werden sollen

24p auf 60fps glätten. Geisterbilder an schnell bewegten Händen vermeiden, Nachziehspuren um dünne Objekte wie Geländer und Haare vermeiden. Der statische Hintergrund muss völlig unbewegt bleiben.

Konkrete Fehlermuster zu benennen ist weit wirksamer als „hohe Qualität“. Das Modell kann seine Ausgabe an konkreten Anweisungen prüfen.

Muster: Bewegung und Textur trennen

In diesem Durchgang nur auf Bewegungsharmonie achten. Bestehende Details und Körnung unverändert lassen – die Texturwiederherstellung erfolgt separat.

Nützlich, wenn Sie zwei Verarbeitungsphasen hintereinanderschalten, sodass jeder Prompt nur eine Zuständigkeit hat.

Muster: Material mit gemischter Bewegung behandeln

Bei Interviewaufnahmen mit fester Kamera und bewegtem Motiv wirkt es gut, die Kamerastarrheit explizit zu nennen:

Auf 60fps interpolieren. Kamera steht – der Hintergrund muss völlig still sein oder flackern. Nur Kopf und Hände der sprechenden Person sollen flüssige Bewegung zeigen.

Widerstehen Sie dem Drang, lange Abhandlungen zu schreiben. Drei Sätze, die Zielbewegung, zu vermeidende Artefakte und was still bleiben muss abdecken, erfassen nahezu alle Fälle.

Prompt-Rezepte für Detailrekonstruktion

Detailrekonstruktion ist die Hälfte der Aufgabe, die plausible feine Struktur erfindet. Das Fehlermuster sind Halluzinationstexturen: Haut wirkt plastikartig, Vegetation wird zu Rauschen, Text wird zu Kauderwelsch. Der Prompt sollte der Erfindung Grenzen setzen.

Muster: An der Quelle verankern

Details konsistent mit den Quellframes rekonstruieren. Keine Texturen erfinden, die die Originalpixel nicht andeuten. Wo Details tatsächlich verloren sind, ein weiches, glaubwürdiges Ergebnis gegenüber geschärftem Rauschen bevorzugen.

Diese eine Anweisung verhindert die meisten Überschärfungs-Pathologien.

Muster: Materialien im Bild benennen

Feine Details von Stofftexturen, Haaren und Hautporen wiederherstellen. Hauttöne natürlich halten, Poren unregelmäßig – ein glattes, airbrushartiges Aussehen vermeiden. Metallische Oberflächen sollen vorhandene Glanzlichter behalten und keine neuen erzeugen.

Materialbezogene Anweisungen geben dem Modell umsetzbare Einschränkungen, ohne einen ganzen Absatz Allgemeinplätze.

Muster: Text und Grafiken schützen

Dieser Ausschnitt enthält Bildschirm-Untertitel und Logos. Text muss klar lesbar und unverzerrt bleiben. Keine grafischen Elemente neu zeichnen oder in ihrem Stil verändern.

Text ist das riskanteste Detail – Kauderwelsch-Untertitel sind schlimmer als leicht unscharfe. Wenn Lesbarkeit entscheidend ist, prüfen Sie sie in der Vergleichsphase, statt dem Prompt zu vertrauen.

Muster: Schärfung bewusst dosieren

Ein zurückhaltendes Maß an Detailwiederherstellung anwenden. Ziel ist Material mit natürlicher Anmutung bei 1080p, kein geschärftes Standbild. Leichte Weichheit ist akzeptabel; Ringing und Haloing sind nicht akzeptabel.

Beides kombinieren

Wenn Sie in einem Durchgang sowohl interpolieren als auch rekonstruieren, schreiben Sie einen Prompt, der beides abdeckt, aber jeder Teilsatz nur ein Anliegen betrifft:

Feine Texturen – Stoffe, Haare, Haut – konsistent mit der Quelle rekonstruieren und plastikartige Glätte vermeiden. Auf 60fps interpolieren, Bewegung stabil, keine Geisterbilder an Händen, Hintergrund völlig still.

Ausgabe vorher und nachher vergleichen

Ein verbessertes Video, das in einem Einzelframe beeindruckend aussieht, kann in der Bewegung zusammenbrechen. Etablieren Sie einen festen Vergleichsablauf und führen Sie ihn bei jeder Änderung von Parametern oder Prompts aus; sonst raten Sie, und Raten ist teuer.

Ein Standard-Testclipset aufbauen

Wählen Sie drei kurze Ausschnitte (je 5–10 Sekunden), die Sie nie ändern:

  1. Einfach – gutes Licht, langsame Bewegung, saubere Quelle. Sollte nahezu perfekt aussehen; wenn nicht, ist irgendwo etwas falsch konfiguriert.
  2. Schwierig – schnelle Bewegung, feine Details oder gemischte Bewegungsarten. Hier treten Interpolationsartefakte auf.
  3. Adversarial – Bildschirmtext, feine Strukturen oder starke vorherige Kompression. Hier zeigen sich Halluzinationen.

Führen Sie jede Prompt- oder Parameteränderung gegen alle drei aus. Eine Änderung, die dem einfachen Ausschnitt hilft, aber dem adversarialen schadet, ist keine Verbesserung.

In dieser Reihenfolge vergleichen

  • Seite an Seite bei 100 % Zoom. Verwenden Sie keine Fensteranpassung, Artefakte verstecken sich dort. Prüfen Sie dieselben Ausschnitte: Gesichter, Textbereiche und Bereiche mit hoher Bewegung.
  • Frame-für-Frame scrubben. Steppen Sie durch schnelle Bewegungsabschnitte und suchen Sie Geisterbilder, Verzerrungen und Flackern.
  • Wiedergabe in Echtzeit. Viele Artefakte verschwinden beim Frame-Scrubben und zeigen sich in Bewegung, und umgekehrt. Sehen Sie sich beides an.
  • Textlesbarkeitsprüfung. Lesen Sie jeden Untertitel in der verbesserten Version gegen die Quelle. Dies ist die schnellste objektive Bestanden/Nicht-bestanden-Prüfung, die Ihnen zur Verfügung steht.

Qualität und Kosten gemeinsam abwägen

Die Abrechnung folgt der Arbeit des Endpoints – Ausgabedauer und Auflösung sind die Treiber; aktuelle Tarife finden Sie im Preisbereich der Website. Praktische Konsequenz: Längere Ausschnitte bringen oft nur marginale Qualitätsverbesserungen, die meist weniger lohnend sind als deutliche Verbesserungen bei kürzeren Ausschnitten. Notieren Sie für jede Kandidatenkonfiguration die erzeugte Ausgabedauer und Auflösung und fragen Sie, ob die sichtbare Verbesserung die Kosten wert ist. Behalten Sie die Gewinner, verwerfen Sie den Rest, und bevor Sie den Endpoint in eine automatisierte Pipeline einbinden, frieren Sie eine Konfiguration ein und dokumentieren Sie sie – Prompt, Parameter und Testergebnisse – damit künftige Änderungen dagegen gemessen werden können.

Häufige Anfrageprobleme beheben

Die meisten Integrationsreibungen mit topaz-upscale/video lassen sich in wenige Kategorien einordnen. Arbeiten Sie sie in dieser Reihenfolge ab.

Authentifizierung und Zugriff

401 bedeutet, der Schlüssel fehlt, ist falsch formatiert oder wurde nicht gesendet – prüfen Sie, ob die Umgebungsvariable tatsächlich in der Shell gesetzt ist, die den Befehl ausführt, und nicht nur im Editor. 403 bedeutet meist, der Schlüssel ist gültig, aber dem Konto fehlt der Zugriff auf dieses Modell. Bestätigen Sie, dass der Modellname exakt topaz-upscale/video lautet.

Der Dienst kann Ihr Video nicht abrufen

Dies ist der häufigste Fehler. Symptom: Die Aufgabe scheitert früh mit einem Download- oder Eingabefehler. Ursachen:

  • Die URL ist privat oder erfordert interaktive Anmeldung.
  • Die signierte URL läuft ab, bevor die Aufgabe den Download-Schritt erreicht – besonders in langen Warteschlangen möglich.
  • Der Host blockiert automatische Anfragen oder ist so langsam, dass er in ein Timeout läuft.

Behebung: Laden Sie die Datei über die Plattform hoch und referenzieren Sie die zurückgegebene Kennung, oder erzeugen Sie beim Absenden eine signierte URL mit großzügiger Gültigkeitsdauer.

Dekodierungsfehler

Wenn der Fehler das Medium statt der Anfrage betrifft, verpacken Sie die Quelle in einen gängigen Container und wiederholen Sie den Versuch. Testen Sie die Datei lokal – wenn Ihr eigener Player schon Mühe hat, wird es der Dienst auch haben.

Aufgabe läuft endlos oder ins Timeout

Lange Quellen brauchen lange, und manche Anfragen dauern unverhältnismäßig lange. Bevor Sie erneut senden, prüfen Sie den Aufgabenstatus anhand der ID – möglicherweise sehen Sie eine wartende statt einer fehlgeschlagenen Aufgabe. Blindes erneutes Senden kann die Kosten verdoppeln. Wenn Sie aus einem Skript abfragen, stellen Sie sicher, dass Ihr Client-Timeout länger ist als die erwartete Aufgabendauer; sonst geben Sie eine Aufgabe auf, die noch ordnungsgemäß läuft.

Ausgabe sieht schlechter aus als die Quelle

Die Anfrage war erfolgreich, aber das Ergebnis ist überschärft, plastikartig oder hat Geisterbilder. Das ist ein Prompt-Problem, kein API-Problem: Kehren Sie zu den Rezepten für Detailrekonstruktion und Interpolation zurück und fügen Sie klare Grenzen hinzu – „konsistent mit der Quelle“, „keine Geisterbilder“, „Hintergrund muss still bleiben“. Führen Sie dann Ihr Standard-Vergleichsset erneut aus.

Intervallartige, nicht reproduzierbare Fehler

Protokollieren Sie bei jedem Aufruf sowohl den vollständigen Anfrage-Body als auch die Aufgaben-ID. Ohne beides können Sie nicht unterscheiden, ob der Fehler aus einer anderen Payload oder einem vorübergehenden Dienstproblem stammt. Mit einem Dutzend protokollierter Fehler wird das Muster meist innerhalb von Minuten sichtbar.

Ähnliche Artikel

Alle Artikel ansehen →

Starte mit persistenten KI-Artefakten

Hol dir deinen API-Key und rufe Bild-, Video- und Audiomodelle über eine einzige task-basierte API auf.

API-Dokumentation lesen