Transparente Figurenanimation mit MCP: vom Bild zum Download

Ein MCP-Animationsauftrag ist nicht fertig, wenn ein KI-Assistent „in der Warteschlange“ meldet oder einen temporären Link liefert. Ein brauchbarer Ende-zu-Ende-Ablauf überträgt echte Bildbytes, zeigt Kosten vor Generierung, wartet auf Endzustand, speichert alle gewünschten Dateien und prüft deren Pixel.

Diese Anleitung dokumentiert einen produktiven AnimGen-MCP-Lauf mit Codex vom 11. September 2026. Aus transparentem PNG erhielten wir Quellvideo, Sprite-Sheet und JSON. Visuelle Prüfung fand anschließend einen Seitenverhältnisfehler im ersten Sheet. Das öffentliche Beispiel nutzt deshalb einen korrigierten Reexport aus exakt demselben heruntergeladenen MP4, ohne zweite Modellgenerierung oder zusätzliche Credits. Lade das vollständige Nachweispaket und prüfe die Enddateien.

Ergebnis auf einen Blick

36 Credits sind die historische Kalkulation dieses Laufs, kein dauerhafter Preis. Verfügbarkeit und Preise kommen aus aktuellen Kontoantworten; frage vor jeder neuen Generierung Modelle und Kosten erneut ab.

Mit echtem transparentem Bild beginnen

Quelle war das öffentliche Pixel-Schwertkämpferinnen-PNG. Es ist echtes RGBA: Alpha 0–255, alle vier Ecken transparent, etwa 27 % der Leinwand mit sichtbarer Figur.

Ein Remote-MCP-Server kann ./character.png auf deinem Rechner nicht öffnen. Der Client ruft prepare_image_upload auf, überträgt exakte Bytes mit zurückgegebenen Methoden/Headern und ruft complete_image_upload auf. Nur dessen file_id gehört in die Animationsanfrage.

In diesem Lauf meldete der fertige Upload dieselben 875.625 Bytes und SHA-256-Prüfsumme wie die lokale Quelle. Temporäre URL und private Datei-ID bleiben außerhalb des öffentlichen Pakets.

Dem MCP-Client einen begrenzten Auftrag geben

Ein wiederverwendbarer Ausgangspunkt beschreibt kreatives Ziel und operative Sicherungen gemeinsam. Hier der Originalprompt:

Use the AnimGen MCP server to turn ./character.png into a transparent,
in-place walk animation for a 2D game.

First call list_models and confirm that Seedance 2.0 Fast supports a
first-frame request at 4 seconds and 480p. Upload the actual PNG bytes;
do not treat the local path as an uploaded image.

Use automatic Alpha Key mode. Request a 16-frame transparent sprite
sheet and matching JSON metadata at 256 × 256 per frame.

Before calling generate_animation, show me the exact request and current
credit quote and wait for my approval. Do not exceed the amount I approve.
Persist one idempotency key, poll the same task to a terminal state, then
download and verify every returned asset without exposing signed URLs.

Das vermeidet drei falsche Abschlussmeldungen: lokalen Pfad für übertragen halten, OAuth als Ausgabenfreigabe behandeln oder URL statt gespeicherter Datei liefern.

Vor Upload verbinden und prüfen

Der Produktionsendpunkt ist https://api.animgen.com/mcp mit Streamable HTTP und OAuth. Ein AnimGen-API-Schlüssel gehört nicht in diese Client-Konfiguration.

Für Codex CLI:

codex mcp add animgen --url https://api.animgen.com/mcp
codex mcp login animgen

Die offizielle Codex-MCP-Dokumentation beschreibt Remote-HTTP-Server und OAuth. AnimGens Client-Anleitung erklärt Endpunkt und weitere kompatible Clients.

Rufe nach OAuth list_models mit leerem Objekt auf. Eine strukturierte Liste prüft Lesezugriff ohne Credits. Hier meldete sie Seedance 2.0 Fast mit Startbildeingabe, mindestens vier Sekunden, 480p und dem unten genutzten Verhältnis adaptive.

Eine Anfrage aufbauen und unverändert halten

Die hochgeladene file_id ist privat und deshalb ersetzt. Alles andere entspricht dem erfolgreichen Lauf:

{
  "input": {
    "first_frame": {
      "type": "file",
      "file_id": "YOUR_COMPLETED_UPLOAD_FILE_ID"
    }
  },
  "prompt": "Static camera. The pixel-art swordswoman faces right and walks in place. Alternate the legs clearly, swing the arms naturally, and let the hair and scarf move slightly. Keep the original character design, pixel-art style, full-body framing, scale, and screen position. Do not move the camera or let the character leave the frame.",
  "video": {
    "model": "volcengine_seedance:doubao-seedance-2-0-fast-260128",
    "duration_seconds": 4,
    "resolution": "480p",
    "ratio": "adaptive",
    "transparency": {
      "mode": "alpha_key",
      "key_selection": "auto"
    }
  },
  "selection": {"mode": "full"},
  "export": {
    "frame_count": 16,
    "output_width": 256,
    "output_height": 256,
    "output_formats": ["spritesheet", "spritesheet_json"],
    "transparent": {"enabled": true}
  }
}

Beide Transparenzeinstellungen sind wichtig. video.transparency.mode wählt Alpha Key im Videoschritt; export.transparent.enabled fordert RGBA-Assets im Export. Eine davon wegzulassen beschreibt nicht denselben Auftrag.

Die Modell-ID dokumentiert den historischen Lauf. Für neue Aufträge verwende eine aktuell von list_models gelieferte ID statt einen unveränderten Katalog anzunehmen.

Erst kalkulieren, dann den bezahlten Aufruf freigeben

quote_animation lieferte 36 Credits: alle für viersekündige Videogenerierung, null zusätzlich für den gewählten 16-Frame-Export dieses Laufs.

Erst nach Anzeige von Anfrage und Betrag genehmigte der Nutzer maximal 36 Credits. Der Client kalkulierte erneut, bestätigte den unveränderten Preis und rief generate_animation so auf:

{
  "idempotency_key": "ONE_PERSISTED_LOGICAL_OPERATION_KEY",
  "quote_id": "FRESH_QUOTE_ID",
  "max_credits": 36,
  "request": {"...": "the unchanged request above"}
}

Kopiere 36 nicht als Budget anderer Anfragen. Verwende den tatsächlich geprüften Betrag. Speichere Anfrage/Idempotenzschlüssel vor Erstellung. Bei unklarer Antwort stelle denselben Auftrag wieder her, statt still neue Kosten zu erzeugen. Der MCP-Ausgabenschutz beschreibt die Grenze.

Auftrag abfragen, dann echte Bytes herunterladen

generate_animation lieferte einen asynchronen Auftrag, keine Animationsdatei. Wir fragten denselben Auftrag durch video_generation und animation_export bis succeeded ab. Ein Zwischen-MP4 erschien vor beiden Export-Assets.

Für jede Ausgabe rief der Client download_asset auf, nutzte die temporäre URL ohne weitergeleitete OAuth-/API-Zugangsdaten und speicherte lokal. Keine signierte URL wurde in Artikel oder Archiv kopiert.

Das Quell-MP4 hat einen einfarbigen Key-Hintergrund. Es ist ein Bewegungszwischenprodukt, nicht die transparente Lieferung.

Transparenz befindet sich in den exportierten PNG-Frames:

Öffne die animierte Schachbrettvorschau für alle 16 Endframes in Reihenfolge.

Sprite-Sheet und JSON gemeinsam prüfen

Das endgültige Sheet ist ein 4 × 4 Raster. JSON nennt Rechteck, Quellgröße und Dauer jeder Zelle; Spiel oder Buildtool müssen das Layout nicht aus dem Bild erraten.

Die Dateiprüfungen ergaben:

• Alle drei ursprünglichen Downloads entsprachen den Byte-Zahlen der MCP-Metadaten.
• Das korrigierte Sheet hatte 809.336 Bytes und bewahrte Quellproportionen.
• PNG war RGBA; jeder Frame enthielt Alpha von 0 bis 255.
• Alle 16 Frame-Bilder waren verschieden.
• Jede geprüfte Frame-Ecke war vollständig transparent.
• Alle 16 JSON-Rechtecke passten zu 256 × 256 Zellen im 1024 × 1024 Sheet.
• JSON-Wiedergabe dauerte 4,048 Sekunden, weniger als 0,01 Sekunden vom Quellvideo entfernt.
• Der Auftrag berechnete einmal die genehmigten 36 Credits, ohne Reservierungsrest oder bezahlte Wiederholung.

Das erkennt Transport-, Paket- und offensichtliche Transparenzfehler. Die Endentscheidung erfordert dennoch sichtbare Bewegung am Ziel.

Visuelle Prüfung fand und behob einen Seitenverhältnisfehler

Der erste Export bestand Datei-, Alpha-, Frame-Anzahl- und JSON-Layouttests, sah aber falsch aus: zu breit und zu kurz. Die Quelle ist 560 × 752, doch der Export skalierte direkt auf 256 × 256. Relativ zur Höhe wurde das Bild etwa 34 % breiter. Wir lehnten dieses technisch gültige, visuell irreführende Sheet ab.

Für das Endbeispiel korrigierten wir den transparenten Exportpfad und wiederholten nur deterministischen Frame-Export derselben MP4. Jeder abgetastete Frame wird nun proportional auf 191 × 256 skaliert und auf 256 × 256 transparent zentriert: 32 Pixel links, 33 rechts. Relativer Verhältnisfehler bleibt unter 0,2 %; sichtbare Pixel haben rechts mindestens 33 Pixel Raum.

Das korrigierte 4 × 4 Sheet behält 16 verschiedene RGBA-Frames, transparente Prüfecken sowie unverändertes JSON-Zellenlayout und 4,048 Sekunden. Quellwiederverwendung brauchte keinen zweiten Modellaufruf und keine Credits über die ursprünglichen 36 hinaus.

AnimGens Eingabe-Leinwand hilft weiterhin, wenn die Figur während Generierung mehr Raum braucht. Sie ist kreative Bildgestaltung, kein Ersatz für proportionserhaltenden Export.

Beispiel herunterladen oder öffentliche API nutzen

Das MCP-Beispielpaket enthält öffentliche Eingabe, exakte Produktions-MP4 und JSON, korrigiertes Sheet, animierte Vorschau, Frame-Prüfbild, README und bereinigte Anfragevorlage. Bewusst fehlen OAuth-Token, signierte URL, kontoeigene ID, Quote-ID, Auftrags-ID und Idempotenzschlüssel.

Ohne KI-Assistenten in deiner Architektur ist ein entsprechender Workflow über die öffentliche API möglich. Beginne beim API-Schnellstart. MCP nutzt OAuth-Tools und kann freigegebene quote_id/max_credits erzwingen; API verwendet Schlüssel und dokumentierte Vorprüfung. Vermische Authentifizierungs- und Ausgabenmodelle nicht.

Für Agenten folge dem vollständigen MCP-Ablauf. Um zuerst eigene Eingaben und Exporte interaktiv zu prüfen, öffne AnimGen Studio.