KI-Bild- und Video-API: Von der Eingabe zur geprüften Ausgabe

Erstellen Sie ein Bild, geben Sie es frei und animieren Sie es dann zu einem kurzen Clip. Diese Schritte folgen unserem Test mit einer blauen Tasse vom Oktober 2026. Wir verwenden ein Z-Image-Standbild für 0,010 $ und fünf Sekunden MiniMax H3 bei 768p für 0,185 $: 0,195 $ für je einen Versuch pro Stufe, bei ausgeschalteter Prompt-Erweiterung für das Standbild. Probieren Sie die Szene zuerst im Playground aus; funktionieren die Eingaben, verwenden Sie das Python-Beispiel oder lassen Sie einen Agent die Aufrufe übernehmen.

Das gewünschte Ergebnis ist konkret: eine sauber geformte Tasse auf einer Werkbank, nach rechts ziehender Dampf und eine langsame Kamerafahrt nach vorn, die in einem Stillstand endet. Sie brauchen weder ein Modell bereitzustellen noch einen GPU-Server einzurichten.

Probieren Sie den vollständigen Ablauf im Playground

Erstellen Sie Ihr Konto und laden Sie Guthaben auf, und bestätigen Sie Ihre E-Mail-Adresse. Der Playground übernimmt die Anfrage; einen API-Schlüssel benötigen Sie erst für den Code und die Agent-Werkzeuge weiter unten.

1. Erstellen Sie das Anfangsbild

Öffnen Sie Z-Image Text-zu-Bild und dessen Playground. Fügen Sie diesen Prompt ein:

Photograph of a handmade blue ceramic mug of tea on a worn wooden workbench in a pottery studio, a thin curl of steam rising from the mug. Soft window light from the left, shallow depth of field, shelves of pots softly out of focus behind. The mug sits left of centre with empty bench to its right. Natural colours, no text, no logos.

Wählen Sie 16:9, PNG, seed 42, und schalten Sie die Prompt-Erweiterung aus. Prüfen Sie den angezeigten Preis und drücken Sie Run model. Das Basisbild kostet 0,010 $; mit Erweiterung wären es 0,016 $. Lassen Sie seed 42 unverändert, wenn Sie Prompt-Änderungen vergleichen.

Öffnen Sie das Ergebnis, bevor Sie fortfahren. Prüfen Sie:

• Objekt: eine Tasse, ein Henkel und saubere Keramikformen.
• Bewegungsspielraum: sichtbarer Dampf und rechts Platz zum Abdriften.
• Komposition: die Tasse steht links von der Mitte; die Regale bleiben ein ruhiger Hintergrund.
• Unerwünschte Details: keine zufälligen Schriftzeichen, Logos oder zusätzlichen Tassen.

Laden Sie das freigegebene PNG als image.png herunter. Ist die Tasse fehlerhaft, ändern Sie einen Satz und erstellen Sie ein neues Bild, bevor Sie Geld für Video ausgeben. Jedes neue Basisbild kostet weitere 0,010 $.

2. Animieren Sie das freigegebene Bild

Öffnen Sie MiniMax H3 Bild-zu-Video, fügen Sie image.png als Input image hinzu und tragen Sie unter Prompt Folgendes ein:

Steam rises from the mug and drifts to the right. The camera pushes in slowly toward the mug, then holds. The mug, bench and shelves stay where they are. Quiet room, a faint ceramic clink.

Setzen Sie Duration auf 5 Sekunden und Resolution auf 768p. Prüfen Sie den Preis und drücken Sie Run model. Dieser Clip kostet 0,185 $; bei 2k wären es 0,290 $.

Der Prompt trennt Dampfbewegung, Kamerabewegung und Ton. Er verlangt, dass die Tasse stehen bleibt, statt sie erneut zu beschreiben. Wandert sie über die Werkbank, vereinfachen Sie die Kameraanweisung, statt weitere Objektaktionen hinzuzufügen. Eine langsame Vorwärtsfahrt bringt die Kamera näher heran; sie fordert keine Bewegung der Tasse.

3. Prüfen Sie den Clip und wählen Sie die nächste Aufnahme

Spielen Sie das gesamte Ergebnis mit Ton ab. Prüfen Sie, dass die Tasse weder rutscht noch ihre Form ändert, die Kamera vorfährt und dann hält, kein unerwünschter Schnitt vorkommt und der Ton zu einem ruhigen Studio passt. Erwartet wird ein etwa fünfsekündiges MP4 mit Audiospur; eine abspielbare Datei allein macht die Aufnahme noch nicht brauchbar.

War das Bild richtig, aber die Bewegung falsch, behalten Sie das freigegebene Anfangsbild und ändern Sie den Bewegungsprompt. War schon das Anfangsbild falsch, ersetzen Sie zuerst dieses. H3 hat keinen seed: Eine Generierung bei 2k ergibt eine neue Aufnahme, deren Bewegung von der bevorzugten 768p-Version abweichen kann.

Was der Test mit der blauen Tasse lieferte

Das Standbild kostete 0,010 $ und wurde als 1280 × 720 PNG geliefert. Die fünfsekündige Videoanfrage kostete 0,125 $ (bei 480p, das nicht mehr angeboten wird; derselbe Clip kostet bei 768p 0,185 $) und lieferte ein 832 × 480 MP4 mit Audiospur. Insgesamt waren es 0,135 $; bei 768p wären es 0,195 $.

Die Tasse blieb auf der Werkbank, während der Dampf nach oben und rechts zog; die Kamerafahrt war dezent. Im Standbild stand die Tasse nur leicht links von der Mitte, und gegen Ende wurde der Dampf nahe dem Regal weniger deutlich. Für eine engere Produktaufnahme präzisieren Sie die Tassenposition im Bildprompt vor der Animation.

Warum diese beiden Modelle für den ersten Versuch passen

Z-Image liefert Ihnen ein günstiges Bild, um Motiv und Komposition festzulegen. H3 übernimmt dieses Bild und erzeugt Bewegung sowie eine Tonspur. Ihre Eingaben unterscheiden sich:

Verwenden Sie ein Anfangsbild als PNG, JPEG, WebP oder GIF, mit Seitenlängen zwischen 256 und 5.760 Pixeln, einem Seitenverhältnis zwischen 2:5 und 5:2 und einer Dateigröße unter 30 MB. Ein hochgeladenes PNG ist die einfachste Eingabe. Ein öffentlicher Bildlink muss das tatsächliche Bild liefern; eine Freigabeseite eines Cloud-Laufwerks ist keine Bildeingabe.

Führen Sie denselben Ablauf mit Python aus

Verwenden Sie Python 3.11 oder neuer, installieren Sie das offizielle Paket mit python -m pip install spicyapi und stellen Sie das Dienstprogramm file bereit. Setzen Sie SPICY_API_KEY in Ihrem eigenen Terminal, speichern Sie den Code als blue-mug.py und starten Sie python blue-mug.py. Er bittet bei beiden kostenpflichtigen Stufen um Zustimmung und pausiert für Ihre Bildprüfung. Behalten Sie beim Fortsetzen den erzeugten Ausführungsordner; wählen Sie einen neuen RUN_NAME nur für einen bewusst neuen Versuch. API-Vertrag und SDK-Optionen finden Sie in der Python-SDK-Dokumentation.

import hashlib
import json
import os
from pathlib import Path
import subprocess
import tempfile
import time
import urllib.request
import uuid
from spicyapi import SpicyClient, output_assets

# Change RUN_NAME for a deliberately new pair of paid generations.
folder = Path(os.getenv("RUN_NAME", "blue-mug-1"))
folder.mkdir(exist_ok=True, mode=0o700)
state_file = folder / "state.json"
state = json.loads(state_file.read_text()) if state_file.exists() else {}
identity = hashlib.sha256(os.environ["SPICY_API_KEY"].encode()).hexdigest()
if state.get("identity", identity) != identity:
    raise RuntimeError("This saved run belongs to a different API key.")
state["identity"] = identity
client = SpicyClient()

def save() -> None:
    temp = state_file.with_suffix(".tmp")
    temp.write_text(json.dumps(state, indent=2))
    temp.chmod(0o600)
    temp.replace(state_file)

def run(stage: str, model: str, inputs: dict) -> dict:
    request = {"model": model, "input": inputs}
    if stage not in state:
        state[stage] = {"request": request, "key": str(uuid.uuid4())}
    saved = state[stage]
    if saved["request"] != request:
        raise RuntimeError("Input changed: choose a new RUN_NAME, not a new retry key.")
    save()  # The same request and key survive a lost create response.
    if not saved.get("taskId"):
        if "first_sent" in saved and time.time() - saved["first_sent"] >= 23 * 3600:
            raise RuntimeError("Unknown acceptance: reconcile task history before retrying.")
        if "quote" not in saved:
            quote = client.quote_task(model=model, input_data=inputs)
            if input(f"{stage}: quoted ${quote['estimatedCost']}. Create? [y/N] ") != "y":
                raise SystemExit("No task created for this stage.")
            saved["quote"] = quote
        saved.setdefault("first_sent", time.time())
        save()
        quote = saved["quote"]
        task = client.create_task(model=model, input_data=inputs,
                                  idempotency_key=saved["key"],
                                  quote_id=quote["quoteId"],
                                  expected_cost=quote["estimatedCost"])
        saved["taskId"] = task["taskId"]
        save()
    task_id = saved["taskId"]
    print(stage, "task:", task_id)
    deadline = time.monotonic() + 1200
    while time.monotonic() < deadline:
        task = client.get_task(task_id)
        if task["state"] in {"failed", "canceled", "expired"}:
            raise RuntimeError(f"{task_id}: {task.get('errorCode')} {task.get('errorMessage')}")
        if task["state"] == "succeeded":
            assets = output_assets(task)
            if not assets or assets[0].get("unavailable"):
                raise RuntimeError(f"{task_id}: no retrievable output; keep the task ID.")
            asset = assets[0]
            if not asset.get("pending") and asset.get("url"):
                print("Charge:", task.get("cost"), "settled:", task.get("settled"))
                return asset
        time.sleep(5)
    raise TimeoutError(f"Resume {task_id} by rerunning this file; do not start another task.")

def download(asset: dict, destination: Path, mime: str) -> None:
    temporary = None
    try:
        request = urllib.request.Request(asset["url"], headers={"User-Agent": "SpicyAPI-Blog-Example/1.0"})
        with urllib.request.urlopen(request, timeout=300) as response:
            if response.status != 200 or response.headers.get_content_type() != mime:
                raise RuntimeError("Unexpected download status or content type.")
            with tempfile.NamedTemporaryFile(dir=folder, delete=False) as handle:
                temporary = Path(handle.name)
                while chunk := response.read(1024 * 1024):
                    handle.write(chunk)
        size = temporary.stat().st_size
        expected = int(asset.get("bytes") or 0)
        detected = subprocess.check_output(["file", "-b", "--mime-type", str(temporary)], text=True).strip()
        if not size or (expected and size != expected) or detected != mime:
            raise RuntimeError("Incomplete or incorrectly formatted download.")
        temporary.replace(destination)  # An interrupted transfer leaves the old file alone.
    finally:
        if temporary is not None:
            temporary.unlink(missing_ok=True)

image_input = {
    "prompt": (
        'Photograph of a handmade blue ceramic mug of tea on a worn wooden workbench '
        'in a pottery studio, a thin curl of steam rising from the mug. Soft window '
        'light from the left, shallow depth of field, shelves of pots softly out of '
        'focus behind. The mug sits left of centre with empty bench to its right. '
        'Natural colours, no text, no logos.'
    ),
    "aspect_ratio": "16:9",
    "output_format": "png",
    "seed": 42,
    "enable_prompt_expansion": False,
}
image_asset = run("image", "alibaba/z-image-turbo/text-to-image", image_input)
download(image_asset, folder / "image.png", "image/png")
if input(f"Open {folder / 'image.png'}. Is the mug/frame approved? [y/N] ") != "y":
    raise SystemExit("Stopped before video generation.")
if not state.get("image_uri"):
    state["image_uri"] = client.upload_file(str(folder / "image.png"))["uri"]
    save()
video_input = {"image_url": state["image_uri"], "prompt": 'Steam rises from the mug and drifts to the right. The camera pushes in slowly toward the mug, then holds. The mug, bench and shelves stay where they are. Quiet room, a faint ceramic clink.',
               "duration_seconds": 5, "resolution": "768p"}
video_asset = run("video", "minimax/h3/image-to-video", video_input)
download(video_asset, folder / "video.mp4", "video/mp4")
print("Play", folder / "video.mp4", "with sound and review it before using it.")

Bewahren Sie den API-Schlüssel auf Ihrem Server oder einem von Ihnen kontrollierten Rechner auf, niemals in einer öffentlichen Webseite oder mobilen App. Prüfen Sie auf den Modellseiten oben die aktuelle Verfügbarkeit und akzeptierten Eingaben, bevor Sie ein anderes Modell integrieren.

Lassen Sie einen Agent die Aufrufe übernehmen

Verwenden Sie einen Agent, wenn er die Eingaben vorbereiten und das Ergebnis zurückgeben soll, während Sie Preis und kreative Entscheidungen freigeben. Prüfen Sie das Anfangsbild selbst, bevor Sie das Video autorisieren.

• CLI: Speichern Sie dasselbe Eingabeobjekt als input.json und verwenden Sie npx @spicyapi/cli tasks create --model alibaba/z-image-turbo/text-to-image --input-file input.json --wait. Die CLI bestätigt den Preis; behalten Sie die zurückgegebene Task-ID zur Wiederaufnahme. Laden Sie für den Clip das freigegebene Standbild mit npx @spicyapi/cli files upload image.png hoch und erstellen Sie minimax/h3/image-to-video auf dieselbe Weise mit der zurückgegebenen spicy://-URI als image_url.
• MCP: Bitten Sie Ihren Assistenten, spicyapi_task_create für alibaba/z-image-turbo/text-to-image und danach spicyapi_task_wait zu verwenden; für den Clip folgt spicyapi_upload_file für das freigegebene image.png, dann spicyapi_task_create mit minimax/h3/image-to-video, 5 Sekunden, 768p und dem Bewegungsprompt oben. Der MCP-Server verlangt vor der Erstellung eine Preisbestätigung.
• Skill: Installieren Sie mit npx skills add spicyapi-ai/spicy-skill und bitten Sie dann $spicyapi, denselben Ablauf auszuführen und für Ihre Freigabe anzuhalten. Der Skill nutzt eine konfigurierte CLI- oder MCP-Verbindung.

Planen Sie ein Budget für Versuche, nicht nur den fertigen Clip

Diese Schätzungen sind in US-Dollar. Bestätigen Sie vor der Generierung den aktuellen Preis.

• Länge und Auflösung: H3 kostet 0,037 $ oder 0,058 $ pro Sekunde bei 768p oder 2k.
• Nicht unterstützte Kombinationen: Ein 4-sekündiger Clip bei 2k wird mit Fehler 40004 abgelehnt.
• Zwei Entwürfe: Ein Standbild und zwei fünfsekündige 768p-Videos kosten 0,380 $.
• Entwurf und Lieferaufnahme: Ein Standbild, eine fünfsekündige 768p-Prüfaufnahme und eine fünfsekündige 2k-Aufnahme kosten 0,010 $ + 0,185 $ + 0,290 $ = 0,485 $; das freigegebene Standbild wird wiederverwendet.

Bei Annahme einer Aufgabe wird Geld reserviert und bei ihrem Ende abgerechnet. Fehlgeschlagene und abgelaufene Aufgaben geben die Reservierung normalerweise frei; bestimmte Inhaltsablehnungen werden gemäß der angegebenen Modellrichtlinie berechnet. Prüfen Sie bei einer Abrechnungsfrage den tatsächlichen cost und den Status settled der Aufgabe.

Beheben Sie das Problem an der richtigen Stelle

Halten Sie den ersten Ablauf klein

Sobald die Aufnahme funktioniert, wählen Sie Lieferlänge und Auflösung und generieren und prüfen Sie diese Aufnahme. Ein optionales Schlussbild kann über H3s last_image_url das Ende lenken; es garantiert weder ein exaktes Schlussbild noch die Bewegung zwischen den Bildern.

Bewahren Sie für eine Anwendung beide Task-IDs und die freigegebenen Dateien in Ihrem eigenen Speicher auf. Nutzen Sie Polling versus Webhooks zur Wahl der Ergebnisabholung, Medienspeicherung zum Aufbewahren der Dateien und Stapelgenerierung für viele Aufnahmen. Der erste Meilenstein bleibt gleich: ein freigegebenes Bild und ein Clip, der tatsächlich Ihrer geplanten Aufnahme folgt.