Video-Upscaling-API: Ein Auslieferungs- und Qualitätssicherungs-Ablauf

Sie haben einen kurzen Clip, der Ihnen gefällt, günstig in 480p erzeugt oder aus älterem Material geschnitten wurde, und er muss in 1080p oder 4K mit intakter Tonspur ausgeliefert werden. Eine Video-Hochskalierungs-API erledigt das in einem einzigen Aufruf, aber dieser Aufruf ist nur die Mitte der Arbeit. Ob die Datei brauchbar ist, entscheidet sich davor (Schnitt abschließen, Quelle prüfen) und danach (rechtzeitig herunterladen, Größe, Länge und Ton bestätigen, exakt die Bildfläche exportieren, die das Ziel verlangt).

Kurz gesagt: Skalieren Sie den endgültigen Schnitt genau einmal auf die Stufe hoch, die das Ziel braucht. SpicyAPI Video Upscaler nimmt eine MP4 von 3 bis 60 Sekunden und eine Stufe entgegen und gibt denselben Clip in höherer Auflösung mit derselben Länge, demselben Seitenverhältnis, derselben Bewegung und derselben Tonspur zurück. Es gibt keinen Prompt. Preise: $0.006 je Quellsekunde bei 720p oder 1080p, $0.012 bei 2K, $0.024 bei 4K.

Was Sie senden und was Sie zahlen

Senden Sie video_url (einen direkten Link auf eine MP4 oder eine hochgeladene Datei) und optional resolution: 720p, 1080p (Standard), 2k oder 4k. Hochgeladene MP4s dürfen bis zu 90 MB groß sein. Die Abrechnung erfolgt je Sekunde des Quellclips, aufgerundet auf eine ganze Sekunde, mit einem Minimum von drei Sekunden.

Die Rundung gilt für jeden eingereichten Clip einzeln, drei 5.2-Sekunden-Clips werden also als 18 Sekunden abgerechnet, nicht als 16. Die vor dem Absenden angezeigte Schätzung geht von einem 60-Sekunden-Clip aus ($0.36 bei 1080p, $1.44 bei 4K); der ungenutzte Teil wird freigegeben, wenn die Task abrechnet, ein 6-Sekunden-Clip wird also für 6 Sekunden berechnet. Eine fehlgeschlagene Task wird erstattet.

Das Kostenargument fürs Hochskalieren liegt auf der Erzeugungsseite. Ein 10-Sekunden-Clip, der mit Seedance 2.5 Spicy in 480p erzeugt wurde, kostet $2.16 pro Versuch; in nativer 1080p kostet er $10.80. Entwerfen Sie in 480p, behalten Sie die Aufnahme, die Sie wollen, und zahlen Sie $0.06, um sie auf 1080p hochzuskalieren. Der Upscaler vergrößert, was bereits im Bild steht, ein Detail, das im Entwurf fehlt, erscheint also nicht. Wenn ein kleines Etikett oder ein Gesicht stimmen muss, prüfen Sie es im Entwurf oder entwerfen Sie in höherer Auflösung.

Bereiten Sie die Quelle vor

Schließen Sie zuerst den Schnitt ab. Trimmen, ordnen und mischen Sie den Ton, bevor Sie hochskalieren. Jede spätere Bearbeitung müsste sonst an einer Datei mit mehrfach so vielen Pixeln wiederholt werden, und Sie zahlen für Sekunden, die Sie wegwerfen. Der Upscaler kann eine falsche Aufnahme nicht reparieren: Eine verzerrte Hand oder ein driftendes Logo kommt größer zurück.

Prüfen Sie die Datei. ffprobe zeigt, was Sie wirklich einreichen, einschließlich einer Dauer, die auf dem Bildschirm auf „60 Sekunden“ gerundet wird, in Wahrheit aber 60.4 beträgt:

ffprobe -v error \
  -show_entries format=duration,size:stream=codec_type,codec_name,width,height,avg_frame_rate,sample_rate,channels \
  -of json approved-source.mp4

Dreierlei sollten Sie prüfen. Die Dauer muss zwischen 3 und 60 Sekunden liegen. Ein Handyclip kann aufrecht abgespielt werden, während der gespeicherte Frame Querformat plus Rotations-Flag ist (ffprobe -show_streams listet es unter side data auf); brennen Sie die Rotation ein, bevor Sie hochladen. Und beachten Sie den Audiostream: Sie vergleichen ihn später mit dem Ergebnis.

Überspringen Sie Clips, die bereits groß genug sind. Ein Clip auf oder über der Stufe kommt in etwa derselben Größe zurück und wird trotzdem berechnet: Ein 786x1178-Clip, der mit 720p gesendet wurde, kam mit 784x1176 zurück. Erfüllt die Quelle bereits die Zielspezifikation, exportieren Sie sie und sind fertig.

Starten Sie vom saubersten Master. Kompressionsblöcke und Rauschen werden mit allem anderen vergrößert. Verwenden Sie den Erzeugungs- oder Schnitt-Master, keine aus einem sozialen Feed neu heruntergeladene Kopie.

Wählen Sie die Stufe nach dem Ziel

Die Stufe ist ein Pixelbudget bei erhaltenem Seitenverhältnis, daher kommen ungewöhnliche Quellen in ungewöhnlichen Größen zurück. Ein 832x480-Clip kam bei 1080p mit 1896x1094 und bei 4K mit 3792x2188 zurück; ein 854x480-Clip kam mit 1922x1080. Erwarten Sie nicht genau 1920x1080.

• 720p oder 1080p für Feeds, Landingpages und Anzeigen. Beide kosten gleich, wählen Sie also nach dem Ziel, nicht nach dem Preis. 1080p ist die Standardeinstellung und meist die richtige Wahl.
• 2K oder 4K für große Displays, Präsentationen oder wenn Sie danach zuschneiden wollen. Sie kosten das Zwei- und Vierfache und dauern länger: etwa 35 Sekunden für einen 5-Sekunden-Job in 1080p und etwa 100 Sekunden bei 4K. Eine 5-Sekunden-Datei in 4K ist rund 19 MB groß.
• Benötigt das Ziel eine exakte Bildfläche, etwa 1080x1920 für einen vertikalen Feed, behandeln Sie das als eigenen Exportschritt nach dem Hochskalieren.

Einen Querformat-Clip hochskalieren und danach vertikal zuschneiden heißt, für Pixel zu bezahlen, die Sie verwerfen. Legen Sie die Kadrierung vor dem Hochskalieren fest und senden Sie die endgültige Komposition.

Probieren Sie es zuerst im Playground aus

1. Öffnen Sie die Video-Upscaler-Seite und bleiben Sie im Tab Playground in der Ansicht Form. Melden Sie sich mit einem Konto mit Guthaben an, um zu starten.
2. Legen Sie die freigegebene MP4 unter Input video ab (bis 90 MB) oder fügen Sie einen direkten Dateilink mit Asset URL ein. Eine Seite, die das Video abspielt, liefert HTML, und der Aufruf schlägt fehl, wobei die Belastung erstattet wird; das Hochladen der Datei ist der zuverlässigste Weg.
3. Setzen Sie Resolution auf 720p, 1080p, 2K oder 4K. Das Feld ist als preisrelevant markiert, und die Schätzung aktualisiert sich mit Ihrer Wahl.
4. Starten Sie den Lauf, spielen Sie das Ergebnis gegen die Quelle ab (siehe die Prüfungen unten) und kopieren Sie es erst dann in Ihren eigenen Speicher.

Ein 5-Sekunden-Clip kostet selbst in 4K nur ein paar Cent, testen Sie also Ihren echten Clip auf der Stufe, mit der Sie ausliefern wollen, bevor Sie Code schreiben.

Rufen Sie ihn dann aus dem Code auf

Installieren Sie das Python SDK (pip install spicyapi), setzen Sie SPICY_API_KEY in Ihrer Serverumgebung und führen Sie aus:

import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

task = client.create_task(
    model="spicyapi/video-upscaler-v1/upscale",
    input_data={
        "video_url": "https://example.com/approved-product-ad.mp4",
        "resolution": "1080p",
    },
    idempotency_key=str(uuid.uuid4()),  # one key per approved clip and tier
)

print("Resume task:", task["taskId"], flush=True)
final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
assets = output_assets(final)
if not assets or any(a.get("pending") or a.get("unavailable") or not a.get("url") for a in assets):
    raise RuntimeError(f"Task {task['taskId']} has no ready output; check this task before a new run")
print(assets[0]["url"])  # copy the file to your own storage now

Erstellen, Warten, Wiederholungen, Fehlercodes und Downloads sind im tasks-Leitfaden und in der Python-SDK-Referenz beschrieben; eine lokale Datei läuft über den kostenlosen Upload-Flow und wird als spicy://-URI übergeben. Der Ergebnislink ist kurzlebig und die Datei bleibt etwa 14 Tage erhalten, lesen Sie also Aufbewahrung und Auslieferung, bevor Sie darauf aufbauen. Eine Task mit Status succeeded bedeutet nur, dass der Dienst fertig ist; markieren Sie den Clip als ausgeliefert, nachdem die Prüfungen unten bestanden sind.

Oder lassen Sie einen Agenten laufen

Wenn ein Assistent die Hochskalierung übernehmen soll, zeigen alle drei offiziellen Tools den Preis und fragen vor einem bezahlten Aufruf nach.

• CLI. Legen Sie {"video_url": "https://example.com/approved-product-ad.mp4", "resolution": "1080p"} in input.json und führen Sie dann aus:

``bash spicyapi tasks create --model spicyapi/video-upscaler-v1/upscale --input-file input.json --wait ``

Siehe die CLI-Dokumentation; npx @spicyapi/cli funktioniert ohne Installation.

• MCP-Server. Fügen Sie den MCP-Server hinzu und fragen Sie dann: „Upscale approved-source.mp4 to 1080p with Video Upscaler.“ Er lädt die Datei mit spicyapi_upload_file hoch, ruft spicyapi_task_create auf, das für Ihre Preisbestätigung anhält, und dann spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill installiert den Agent Skill, der einen Coding-Assistenten das aktuelle Modell-Schema lesen lässt, statt Felder zu raten.

Prüfen Sie das Ergebnis gegen die Quelle

Führen Sie dieselbe Sonde auf beiden Dateien aus und vergleichen Sie. Das ist ein kurzes Skript, das eine Zeile pro Clip ausgibt:

probe() {
  ffprobe -v error -of json \
    -show_entries format=duration,size:stream=codec_type,codec_name,width,height,avg_frame_rate,sample_rate,channels,duration "$1" |
  jq -c '{size_bytes: (.format.size|tonumber), duration: (.format.duration|tonumber),
    video: (.streams|map(select(.codec_type=="video"))[0]|{codec:.codec_name,w:.width,h:.height,fps:.avg_frame_rate}),
    audio: (.streams|map(select(.codec_type=="audio"))[0]|if .==null then null else {codec:.codec_name,rate:.sample_rate,ch:.channels} end)}'
}
probe approved-source.mp4
probe returned.mp4

Was Sie bestätigen müssen:

1. Größe und Format. Das Seitenverhältnis passt zur Quelle, und die Abmessungen sind die, die die Stufe liefern sollte. Notieren Sie die tatsächliche Breite und Höhe; übernehmen Sie sie nicht aus dem Stufennamen.
2. Länge. Die Dauer passt zur Quelle. Hängt Ihr Ziel an exakten Schnittpunkten, prüfen Sie das erste und das letzte Bild, nicht nur eine gerundete Zahl.
3. Ton. Die zurückgegebene Datei hat einen Audiostream mit derselben Kanalzahl und derselben Länge wie die Quelle. Dass ein Stream überhaupt existiert, ist kein Beweis für seine Richtigkeit, spielen Sie also beide Dateien an denselben Stellen ab: das erste gesprochene Wort, einen Schnitt, die letzte Phrase. War die Quelle absichtlich stumm, sollte es das Ergebnis auch sein.
4. Bewegtes Bild. Sehen Sie sich den ganzen Clip in normaler Geschwindigkeit an, bevor Sie Standbilder prüfen. Flimmern, schimmernde Texturen und Halos um bewegte Kanten zeigen sich in der Wiedergabe und selten in einem Standbild.
5. Details, die Bedeutung tragen. Produktetiketten, Logos, Text und Gesichter sind die Stellen, an denen ein Upscaler plausibles Detail erfinden kann, statt echtes Detail wiederherzustellen. Vergleichen Sie sie mit der Quelle im selben Ausschnitt. Ein verändertes Markenzeichen macht den Clip unbrauchbar, so scharf er auch aussieht.

Um einen Moment nebeneinander zu vergleichen, wobei die Quelle mit Nearest-Neighbour auf die Ausgabegröße vergrößert wird, damit Sie ihre echten Pixel sehen:

ffmpeg -ss 2.0 -i returned.mp4 -ss 2.0 -i approved-source.mp4 \
  -filter_complex "[1:v]scale=1896:1094:flags=neighbor[s];[s][0:v]hstack" \
  -frames:v 1 compare-at-2s.png

Setzen Sie die Skalierung auf die zurückgegebene Breite und Höhe.

Exportieren Sie die exakte Auslieferungsdatei

Wenn das Ziel eine feste Bildfläche braucht, schließen Sie mit einem lokalen Export ab. Das Beispiel nimmt eine ungefähr vertikale Quelle wie 2:3 an; ein in 1080x1920 gepolstertes Querformat lässt einen schmalen Bildstreifen frei. Padding behält das ganze Bild, Cropping füllt die Fläche, schneidet aber die Ränder ab, sehen Sie sich das Produkt also nach beidem an.

ffmpeg -i accepted-upscale.mp4 \
  -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2" \
  -c:v libx264 -pix_fmt yuv420p -crf 18 \
  -c:a aac -b:a 192k delivery-vertical.mp4

Dieser Schritt kodiert den Ton neu. Wenn Sie die Originalspur unverändert brauchen, verwenden Sie -c:a copy, sofern das Ziel es akzeptiert, und führen Sie danach die Sonde erneut auf der exportierten Datei aus. Brennen Sie Untertitel und Grafiken nach dem Hochskalieren ein, damit die Kanten der Buchstaben in der endgültigen Größe gezeichnet und nicht vergrößert werden.

Behalten Sie drei Dateien: die freigegebene Quelle, das unveränderte Hochskalieren und jeden Export. Ein späterer Beschnitt oder Re-Export kostet Sie dann nie eine zweite Hochskalierung.

Wenn etwas schiefgeht

Beheben Sie die Stufe, die fehlgeschlagen ist, statt die Hochskalierung neu zu starten.

Ein Pilotlauf vor einem Stapel

Führen Sie einen Clip mit echter Bewegung und Tonspur durch den gesamten Pfad: Sonde, Hochskalierung, Download, Vergleich, Export und dann Abspielen der Enddatei im tatsächlichen Ziel (dem Feed, dem Player, dem großen Display). Lokale Player und Plattformen dekodieren und komprimieren unterschiedlich, nur das Ziel zeigt, ob das Ergebnis standhält. Für einen Stapel nehmen Sie eine schnelle Kamerafahrt, eine schnittdichte Anzeige und einen Clip mit feiner Textur auf und notieren Sie für jeden Clip die Ausgangsdauer, die abgerechneten Sekunden, die Stufe, die endgültige Belastung und den Grund für eine Ablehnung.

Wenn Sie Stufen abwägen, halten Sie den Clip konstant und vergleichen Sie 1080p mit 4K in der Größe, in der er betrachtet wird. Erfüllt 1080p bereits das Ziel, bringt der zusätzliche Betrag von $0.018 je Sekunde nichts Sichtbares.

Die Entscheidung

Behandeln Sie die zurückgegebene Datei als Master, den Sie prüfen, nicht als fertige Lieferung. Der Aufruf kostet ein paar Cent; die vermeidbaren Kosten sind ein wiederholter Schnitt in höherer Auflösung, das Hochskalieren eines bereits ausreichend großen Clips und der Versand einer Datei, deren Ton oder Produktetikett sich verändert hat. Öffnen Sie die Modellseite des Video Upscalers, um einen Clip zu testen.