Vorschau, Auswahl und Export mit Ziel-FPS

Die Quelle nur einmal generieren

Erstelle ein Video mit /v1/video-generations und behalte seine Asset-ID aus outputs[]. Nutze sie für Metadaten, Vorschauen und /v1/animation-exports. Änderungen an Abschnitt oder FPS erfordern keine neue Quellbewegung.

Video-Assets aus Auftragsabfragen und GET /v1/assets/{id} enthalten media: gemessene duration_seconds, durchschnittliche Quell-fps, decodierte frame_count, Anzeige-width und height. Unbekannte Werte sind null. Angeforderte Anbieterdauer und geschätzte Zahlen ersetzen keine Messung. Durchschnitts-FPS lokalisieren bei variabler Bildrate keine einzelnen Frames.

Neue Videos speichern eine Präsentationszeitleiste. Ältere werden bei Asset-Abfrage, Vorschau oder FPS-Export untersucht. Ohne zuverlässiges Timing schlägt FPS-Export fehl; die Quelle bleibt herunterladbar.

Quellzeitpunkte prüfen

Sende an /v1/assets/{asset_id}/preview:

{
  "timestamps_seconds": [0, 1, 2, 3, 4],
  "max_frame_size": 256
}

Jeder Zeitpunkt muss in [0, gemessene Dauer) liegen. Duplikate und unsortierte Zeitpunkte sind erlaubt. Die Antwort enthält einen beschrifteten Kontaktbogen in Anfragereihenfolge: image ist ein erneuerbares Bild-Asset, width/height seine Abmessungen und cells[] enthält index, requested_time_seconds, source_time_seconds und rect. Rechtecke verwenden Pixelkoordinaten ab oben links und schließen Beschriftungen aus.

Lade image.download_url ohne API-/OAuth-Zugangsdaten. Erneuere abgelaufene Links über image.id. Vorschau nutzt weder KI noch Hintergrundentfernung oder Interpolation und zeigt nicht die endgültige Alpha-Qualität.

Vorschauen kosten derzeit keine Credits. Zwischengespeicherte Bilder zählen zum Kontospeicher und folgen regulärer Asset-Aufbewahrung ohne eigenes zeitbasiertes Ablaufdatum. Identische Anfragen verwenden verfügbare Vorschauen erneut.

Einen Abschnitt mit FPS exportieren

Sende zuerst an /v1/animation-exports/quote. Prüfe Credits und resolved_export und sende dieselbe Anfrage mit neuem Idempotency-Key an /v1/animation-exports. Ersetze die Beispiel-UUID durch eine eigene Video-Asset-ID.

{
  "source_video_asset_id": "00000000-0000-4000-8000-000000000003",
  "selection": {"mode": "range", "start_seconds": 1, "duration_seconds": 2},
  "export": {
    "fps": 12,
    "output_formats": ["spritesheet", "spritesheet_json"],
    "output_width": 512,
    "output_height": 512,
    "transparent": {"enabled": true}
  }
}

Transparenter Export benötigt weiterhin eine alpha_key-Quelle. Das Flag entfernt keinen beliebigen Hintergrund. Lasse transparent weg, wenn es nicht benötigt wird.

Die erste FPS-Version erfordert sowohl spritesheet als auch spritesheet_json; ohne Formate wird dieses Paar gewählt. Andere Kombinationen werden abgelehnt. Ältere Exporte mit Frame-Anzahl behalten ihre Formatunterstützung.

Timing-Vertrag

• FPS tastet mit Quellwiedergabegeschwindigkeit ab. Es ist weder Geschwindigkeitsregler noch KI-Interpolation.
• Bei Start S, Dauer T und FPS F ist das Intervall [S,S+T); Abtastpunkte sind S+i/F ohne Endpunkt.
• Die Anzahl ist ceil(T×F). Relatives Dezimal-Serialisierungsrauschen innerhalb 10^-12 einer ganzzahligen Frame-Grenze wird aufgefangen; FPS-Eingaben werden nicht abgeschnitten.
• Gewählt wird der am Präsentationszeitpunkt sichtbare Quellframe. Bei Wiederholungen oder Abtastrate über dem Quelldurchschnitt meldet resolved_export.warnings SOURCE_FRAMES_REPEATED.
• Kumulative Wiedergabegrenzen werden mit positiver kaufmännischer Rundung auf Millisekunden gerundet; benachbarte Grenzen werden subtrahiert. Eine Sekunde bei 24 FPS ergibt Frame-Dauern von 41/42 ms mit insgesamt 1000 ms.
• 1,1 Sekunden bei 12 FPS ergeben 14 Frames mit 17 ms für den letzten Frame und insgesamt 1100 ms. Der Rest wird weder verworfen noch auf andere Frames verteilt.
• Ein auf 0 ms quantisierter Rest führt zu TIME_PRECISION_UNSUPPORTED; passe das Intervall an.
• Die frameweise duration im Aseprite-JSON steuert Wiedergabe. meta.animgen.fps bleibt die angeforderte Abtastrate. Ungleiche Dauern ergeben frameDurationMs: null.

Kalkulation und Auftrag verwenden denselben gespeicherten Sampling-Plan. resolved_export erfolgreicher Aufträge stimmt mit dem Manifest überein. Polling liefert aufgelöstes Intervall, FPS, Anzahl, Gesamtmillisekunden und Warnungen statt aller Abtastpunkte.

Limits, Kompatibilität und Wiederherstellung

Standardlimits: höchstens 60 FPS und 240 Frames, Frame-Abmessungen 64–1024 Pixel, Auswahl 0,1–15 Sekunden, Sheet-Seiten maximal 8192 Pixel und Fläche höchstens 67.108.864 Pixel. Konfigurierte Limits stehen im aktuellen Schema und x-animgen-media-limits in OpenAPI. Überschreitungen liefern Fehler, niemals stillschweigend reduzierte FPS.

Vorschau unterstützt bis zu 12 Zeitpunkte und 32–512 Pixel je Miniaturseite; Standardlimits sind 4.194.304 Ausgabepixel und 10 MiB. Medienprüfung/Vorschau erlaubt zwei gleichzeitige Anfragen pro Dienstprozess, 30 Sekunden Medienbudget und höchstens fünf Sekunden je Downloadverbindung/-Lesevorgang. Quelllimits: 256 MiB, 120 Sekunden, 18.000 decodierte Frames und 16.777.216 Pixel pro Frame. Auslastung liefert wiederholbares MEDIA_BUSY, Decodierungs-Timeout MEDIA_TIMEOUT. Diese Budgets sind konfigurierbar.

fps und frame_count schließen sich aus. Ohne beide bleibt der Standard von 24 Frames. Bestehende Aufträge und Frame-Anzahl-Anfragen behalten bisheriges Sampling und Auswahltoleranz. FPS-Anfragen lehnen Bereiche außerhalb der Quelle ab; full nutzt die tatsächliche Dauer und erfordert Start null ohne angegebene Dauer.

Der Ein-Aufruf-Endpunkt /v1/animations und MCP generate_animation bleiben Frame-Anzahl-Workflows und lehnen FPS ab. Nutze für FPS gestufte Generierung und anschließend Kalkulation der vorhandenen Quelle. API-Kostenvoranschläge binden keine Preise und akzeptieren keine MCP-exklusiven quote_id-/max_credits-Felder.

Gleiche Zugangsdaten, Idempotenzschlüssel und Anfrage liefern denselben Auftrag. Ändere den Schlüssel bei anderem Bereich/FPS. Die Wiederholung eines fehlgeschlagenen Auftrags liefert denselben Fehler; korrigierter Export nutzt neuen Schlüssel und dieselbe Quelle. Exportabbruch oder -fehler löscht das Quellvideo nicht.

Quellvideos haben kein separates zeitbasiertes Ablaufdatum. Asset-/Auftragslöschung und Kontoregeln beeinflussen den Zugriff weiterhin; dies ist keine dauerhafte Sicherungsgarantie. Signierte URL-Gültigkeit und Aufbewahrung sind unabhängig. Lade dauerhaft benötigte Dateien herunter.

Entsprechende MCP-Tools

1. quote_video_generation → freigegebene Ausgabe → generate_video → get_video_generation.
2. Video-Asset-ID behalten; media mit download_asset, Abschnitte mit preview_video prüfen.
3. quote_animation_export → freigegebene Ausgabe → export_animation → get_animation_export.
4. Ausgaben herunterladen und die Dauer jedes Manifest-Frames verwenden.

quote_id/max_credits und idempotency_key stehen neben request. Kalkulationen sind an Operationstyp gebunden; Exportkalkulation zusätzlich an Quelle, Intervall und Einstellungen. Brich mit cancel_video_generation oder cancel_animation_export und task_id ab. Bild-Upload nutzt bestehende Upload-Tools.