Skill zur Videogenerierung
Dieses Skill führt in die Implementierung von Videogenerierungsfunktionen mit dem z-ai-web-dev-sdk-Paket ein und ermöglicht KI-Modellen, Videos aus Textbeschreibungen oder Bildern durch asynchrone Aufgabenverarbeitung zu erstellen.
Skills-Pfad
Skill-Verzeichnis: {project_path}/skills/video-generation
Dieses Skill befindet sich im oben genannten Pfad Ihres Projekts.
Referenzskripte: Beispiel-Testskripte finden Sie im Verzeichnis {Skill Location}/scripts/ für schnelle Tests und als Referenz. Siehe {Skill Location}/scripts/video.ts für ein funktionierendes Beispiel.
Übersicht
Mit der Videogenerierung können Sie Anwendungen erstellen, die Videoinhalte aus Text-Prompts oder Bildern generieren, mit anpassbaren Parametern wie Auflösung, Bildrate, Dauer und Qualitätseinstellungen. Die API verwendet ein asynchrones Aufgabenmodell, bei dem Sie eine Aufgabe erstellen und die Ergebnisse abfragen.
WICHTIG: z-ai-web-dev-sdk DARF NUR im Backend-Code verwendet werden. Verwenden Sie es niemals im clientseitigen Code.
Voraussetzungen
Das z-ai-web-dev-sdk-Paket ist bereits installiert. Importieren Sie es wie in den folgenden Beispielen gezeigt.
CLI-Nutzung (für einfache Aufgaben)
Für einfache Videogenerierungsaufgaben können Sie die z-ai-CLI anstelle von Code verwenden. Die CLI übernimmt die Aufgabenerstellung und das Polling automatisch, ideal für schnelle Tests und einfache Automatisierung.
Einfaches Text-zu-Video
# Video mit automatischem Polling generieren
z-ai video --prompt "Eine Katze spielt mit einem Ball" --poll
# Mit kurzen Optionen
z-ai video -p "Wunderschöne Berglandschaft" --poll
Benutzerdefinierte Qualität und Einstellungen
# Qualitätsmodus (Geschwindigkeit oder Qualität)
z-ai video -p "Meereswellen bei Sonnenuntergang" --quality quality --poll
# Benutzerdefinierte Auflösung und FPS
z-ai video \
-p "Stadt-Zeitraffer" \
--size "1920x1080" \
--fps 60 \
--poll
# Benutzerdefinierte Dauer (5 oder 10 Sekunden)
z-ai video -p "Feuerwerk" --duration 10 --poll
Bild-zu-Video
WICHTIG: Für den Parameter image_url wird dringend empfohlen, base64-codierte Bilddaten anstelle von URLs zu verwenden. Dieser Ansatz ist zuverlässiger und vermeidet potenzielle Netzwerkprobleme oder Zugriffsbeschränkungen.
Hinweis: Passen Sie den MIME-Typ im Daten-URI an Ihr tatsächliches Bildformat an (image/jpeg, image/png, image/webp usw.), um Decodierungsprobleme zu vermeiden.
# Video aus einem einzelnen Bild mit base64 generieren (EMPFEHLUNG)
# Konvertieren Sie Ihr Bild in base64 mit dem korrekten MIME-Typ
# Für PNG-Bilder
IMAGE_BASE64=$(base64 -i bild.png)
z-ai video \
--image-url "data:image/png;base64,${IMAGE_BASE64}" \
--prompt "Die Szene zum Leben erwecken" \
--poll
# Für JPEG-Bilder
IMAGE_BASE64=$(base64 -i foto.jpg)
z-ai video \
--image-url "data:image/jpeg;base64,${IMAGE_BASE64}" \
--prompt "Die Szene zum Leben erwecken" \
--poll
# Für WebP-Bilder
IMAGE_BASE64=$(base64 -i bild.webp)
z-ai video \
--image-url "data:image/webp;base64,${IMAGE_BASE64}" \
--prompt "Die Szene zum Leben erwecken" \
--poll
# URL verwenden (weniger empfohlen, kann Zuverlässigkeitsprobleme haben)
z-ai video \
-i "https://beispiel.com/foto.jpg" \
-p "Bewegung zu dieser Szene hinzufügen" \
--poll
Erstes-Letztes-Bild-Modus
WICHTIG: Verwenden Sie aus Gründen der Zuverlässigkeit base64-codierte Bilder anstelle von URLs. Stellen Sie sicher, dass der MIME-Typ mit Ihrem tatsächlichen Bildformat übereinstimmt.
# Video zwischen zwei Bildern mit base64 generieren (EMPFEHLUNG)
# Stellen Sie sicher, dass der korrekte MIME-Typ für jedes Bild verwendet wird
# Beispiel mit PNG-Bildern
START_BASE64=$(base64 -i start.png)
ENDE_BASE64=$(base64 -i ende.png)
z-ai video \
--image-url "data:image/png;base64,${START_BASE64},data:image/png;base64,${ENDE_BASE64}" \
--prompt "Sanfter Übergang zwischen den Bildern" \
--poll
# Beispiel mit JPEG-Bildern
START_BASE64=$(base64 -i start.jpg)
ENDE_BASE64=$(base64 -i ende.jpg)
z-ai video \
--image-url "data:image/jpeg;base64,${START_BASE64},data:image/jpeg;base64,${ENDE_BASE64}" \
--prompt "Sanfter Übergang zwischen den Bildern" \
--poll
# URLs verwenden (weniger empfohlen)
z-ai video \
--image-url "https://beispiel.com/start.png,https://beispiel.com/ende.png" \
--prompt "Sanfter Übergang zwischen den Bildern" \
--poll
Mit Audiogenerierung
# Video mit KI-generierten Audio-Effekten
z-ai video \
-p "Gewittersturm nähert sich" \
--with-audio \
--poll
Ausgabe speichern
# Aufgabenergebnis in JSON-Datei speichern
z-ai video \
-p "Sonnenaufgang über den Bergen" \
--poll \
-o video_ergebnis.json
Benutzerdefinierte Polling-Parameter
# Polling-Verhalten anpassen
z-ai video \
-p "Tanzender Roboter" \
--poll \
--poll-interval 10 \
--max-polls 30
# Aufgabe ohne Polling erstellen (Aufgaben-ID abrufen)
z-ai video -p "Abstrakte Kunst-Animation" -o aufgabe.json
CLI-Parameter
--prompt, -p <text>: Optional - Textbeschreibung des Videos--image-url, -i <daten>: Optional - Vorzugweise base64-codierte Bilddaten (z.B. "data:image/png;base64,iVBORw..."). URLs werden ebenfalls unterstützt, sind aber weniger empfohlen. Für zwei Bilder kommagetrennte Werte verwenden.--quality, -q <modus>: Optional - Ausgabemodus:speedoderquality(Standard: speed)--with-audio: Optional - KI-Audioeffekte generieren (Standard: false)--size, -s <auflösung>: Optional - Videoauflösung (z.B. "1920x1080")--fps <rate>: Optional - Bildrate: 30 oder 60 (Standard: 30)--duration, -d <sekunden>: Optional - Dauer: 5 oder 10 Sekunden (Standard: 5)--model, -m <modell>: Optional - Zu verwendendes Modell--poll: Optional - Automatisches Polling, bis die Aufgabe abgeschlossen ist--poll-interval <sekunden>: Optional - Polling-Intervall (Standard: 5)--max-polls <anzahl>: Optional - Maximale Polling-Versuche (Standard: 60)--output, -o <pfad>: Optional - Ausgabedateipfad (JSON-Format)
Unterstützte Auflösungen
1024x1024768x1344864x11521344x7681152x8641440x720720x14401920x1080(und andere Standardauflösungen)
Aufgabenstatus später prüfen
Wenn Sie eine Aufgabe ohne --poll erstellen, können Sie den Status später überprüfen:
# Aufgaben-ID aus der ersten Antwort abrufen
z-ai async-result --id "aufgaben-id-hier" --poll
Wann CLI vs. SDK verwenden
CLI verwenden für:
- Schnelle Videogenerierungstests
- Einfache einmalige Videoerstellung
- Befehlszeilen-Automatisierungsskripte
- Testen verschiedener Prompts und Einstellungen
SDK verwenden für:
- Batch-Videogenerierung mit benutzerdefinierter Logik
- Integration in Webanwendungen
- Benutzerdefiniertes Aufgabenwarteschlangenmanagement
- Produktionsanwendungen mit komplexen Workflows
Videogenerierungs-Workflow
Die Videogenerierung folgt einem zweistufigen asynchronen Muster:
- Aufgabe erstellen: Videogenerierungsanfrage senden und eine Aufgaben-ID erhalten
- Ergebnisse abfragen: Aufgabenstatus abfragen, bis sie abgeschlossen ist, und die Video-URL abrufen
Grundlegende Videogenerierungs-Implementierung
Einfache Text-zu-Video-Generierung
import ZAI from 'z-ai-web-dev-sdk';
async function generateVideo(prompt) {
try {
const zai = await ZAI.create();
// Videogenerierungsaufgabe erstellen
const task = await zai.video.generations.create({
prompt: prompt,
quality: 'speed', // 'speed' oder 'quality'
with_audio: false,
size: '1920x1080',
fps: 30,
duration: 5
});
console.log('Aufgaben-ID:', task.id);
console.log('Aufgabenstatus:', task.task_status);
// Ergebnisse abfragen
let result = await zai.async.result.query(task.id);
let pollCount = 0;
const maxPolls = 60;
const pollInterval = 5000; // 5 Sekunden
while (result.task_status === 'PROCESSING' && pollCount < maxPolls) {
pollCount++;
console.log(`Polling ${pollCount}/${maxPolls}: Status ist ${result.task_status}`);
await new Promise(resolve => setTimeout(resolve, pollInterval));
result = await zai.async.result.query(task.id);
}
if (result.task_status === 'SUCCESS') {
// Video-URL aus mehreren möglichen Feldern abrufen
const videoUrl = result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video;
console.log('Video-URL:', videoUrl);
return videoUrl;
} else {
console.log('Aufgabe fehlgeschlagen oder noch in Bearbeitung');
return null;
}
} catch (error) {
console.error('Videogenerierung fehlgeschlagen:', error.message);
throw error;
}
}
// Verwendung
const videoUrl = await generateVideo('Eine Katze spielt mit einem Ball.');
console.log('Generiertes Video:', videoUrl);
Bild-zu-Video-Generierung
WICHTIG: Der Parameter image_url akzeptiert sowohl base64-codierte Bilddaten als auch URLs, aber base64-Codierung wird dringend empfohlen für bessere Zuverlässigkeit und zur Vermeidung netzwerkbezogener Probleme.
Kritisch: Stimmen Sie den MIME-Typ in Ihrem base64-Daten-URI immer mit dem tatsächlichen Bildformat ab, um Decodierungsfehler zu vermeiden.
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
// Hilfsfunktion zum Erkennen des MIME-Typs aus der Dateierweiterung
function getMimeType(filePath) {
const ext = path.extname(filePath).toLowerCase();
const mimeTypes = {
'.jpg': 'image/jpeg',
'.jpeg': 'image/jpeg',
'.png': 'image/png',
'.gif': 'image/gif',
'.webp': 'image/webp',
'.bmp': 'image/bmp'
};
return mimeTypes[ext] || 'image/jpeg'; // Standard JPEG, falls unbekannt
}
async function generateVideoFromImage(imagePath, prompt) {
const zai = await ZAI.create();
// Methode 1: base64-codiertes Bild verwenden (EMPFEHLUNG)
// MIME-Typ automatisch aus Dateierweiterung erkennen
const imageBuffer = fs.readFileSync(imagePath);
const mimeType = getMimeType(imagePath);
const base64Image = `data:${mimeType};base64,${imageBuffer.toString('base64')}`;
const task = await zai.video.generations.create({
image_url: base64Image, // Base64-Datenstring mit korrektem MIME-Typ
prompt: prompt,
quality: 'quality',
duration: 5,
fps: 30
});
return task;
}
// Methode 2: URL verwenden (weniger empfohlen)
async function generateVideoFromImageUrl(imageUrl, prompt) {
const zai = await ZAI.create();
const task = await zai.video.generations.create({
image_url: imageUrl, // URL-String
prompt: prompt,
quality: 'quality',
duration: 5,
fps: 30
});
return task;
}
// Verwendungsbeispiele
const task1 = await generateVideoFromImage(
'./images/foto.jpg', // Funktioniert mit JPEG
'Animieren Sie diese Szene mit sanfter Bewegung'
);
const task2 = await generateVideoFromImage(
'./images/grafik.png', // Funktioniert mit PNG
'Fügen Sie dynamische Bewegung hinzu'
);
const task3 = await generateVideoFromImage(
'./images/animation.webp', // Funktioniert mit WebP
'Erwecken Sie dies zum Leben'
);
Bild-zu-Video mit Start- und Endbild
WICHTIG: Für den Keyframe-Modus werden base64-codierte Bilder dringend empfohlen gegenüber URLs, um eine konsistente und zuverlässige Videogenerierung zu gewährleisten. Verwenden Sie immer den korrekten MIME-Typ für jedes Bild.
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
// Hilfsfunktion zum Erkennen des MIME-Typs aus der Dateierweiterung
function getMimeType(filePath) {
const ext = path.extname(filePath).toLowerCase();
const mimeTypes = {
'.jpg': 'image/jpeg',
'.jpeg': 'image/jpeg',
'.png': 'image/png',
'.gif': 'image/gif',
'.webp': 'image/webp',
'.bmp': 'image/bmp'
};
return mimeTypes[ext] || 'image/jpeg';
}
async function generateVideoWithKeyframes(startImagePath, endImagePath, prompt) {
const zai = await ZAI.create();
// Methode 1: base64-codierte Bilder verwenden (EMPFEHLUNG)
// MIME-Typ automatisch für jedes Bild erkennen
const startBuffer = fs.readFileSync(startImagePath);
const endBuffer = fs.readFileSync(endImagePath);
const startMimeType = getMimeType(startImagePath);
const endMimeType = getMimeType(endImagePath);
const startBase64 = `data:${startMimeType};base64,${startBuffer.toString('base64')}`;
const endBase64 = `data:${endMimeType};base64,${endBuffer.toString('base64')}`;
const task = await zai.video.generations.create({
image_url: [startBase64, endBase64], // Array von base64-Strings mit korrekten MIME-Typen
prompt: prompt,
quality: 'quality',
duration: 10,
fps: 30
});
console.log('Aufgabe mit Keyframes erstellt:', task.id);
return task;
}
// Methode 2: URLs verwenden (weniger empfohlen)
async function generateVideoWithKeyframesUrl(startImageUrl, endImageUrl, prompt) {
const zai = await ZAI.create();
const task = await zai.video.generations.create({
image_url: [startImageUrl, endImageUrl], // Array von URL-Strings
prompt: prompt,
quality: 'quality',
duration: 10,
fps: 30
});
console.log('Aufgabe mit Keyframes erstellt:', task.id);
return task;
}
// Verwendungsbeispiele mit verschiedenen Formaten
const task1 = await generateVideoWithKeyframes(
'./frames/start.jpg', // JPEG-Startbild
'./frames/end.jpg', // JPEG-Endbild
'Sanfter Übergang zwischen diesen Szenen'
);
const task2 = await generateVideoWithKeyframes(
'./frames/start.png', // PNG-Startbild
'./frames/end.webp', // WebP-Endbild - verschiedene Formate funktionieren!
'Morphing-Effekt zwischen Bildern'
);
Asynchrones Ergebnis-Management
Aufgabenstatus abfragen
import ZAI from 'z-ai-web-dev-sdk';
async function checkTaskStatus(taskId) {
try {
const zai = await ZAI.create();
const result = await zai.async.result.query(taskId);
console.log('Aufgabenstatus:', result.task_status);
if (result.task_status === 'SUCCESS') {
// Video-URL aus Ergebnis extrahieren
const videoUrl = result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video;
if (videoUrl) {
console.log('Video-URL:', videoUrl);
return { success: true, url: videoUrl };
}
} else if (result.task_status === 'PROCESSING') {
console.log('Aufgabe wird noch verarbeitet');
return { success: false, status: 'processing' };
} else if (result.task_status === 'FAIL') {
console.log('Aufgabe fehlgeschlagen');
return { success: false, status: 'failed' };
}
} catch (error) {
console.error('Fehler beim Abfragen des Aufgabenstatus:', error.message);
throw error;
}
}
Automatisches Polling mit Timeout
import ZAI from 'z-ai-web-dev-sdk';
async function pollWithTimeout(taskId, maxPolls = 60, pollIntervalMs = 5000) {
const zai = await ZAI.create();
for (let i = 0; i < maxPolls; i++) {
const result = await zai.async.result.query(taskId);
console.log(`Polling ${i + 1}/${maxPolls}: Status ist ${result.task_status}`);
if (result.task_status === 'SUCCESS') {
return { status: 'success', result };
} else if (result.task_status === 'FAIL') {
return { status: 'failed', result };
} else if (result.task_status !== 'PROCESSING') {
// Status kann auch 'QUEUED' oder andere sein – in Bearbeitung lassen
}
if (i < maxPolls - 1) {
await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
}
}
return { status: 'timeout', result: null };
}
// Verwendung
const pollResult = await pollWithTimeout(taskId, 30, 10000);
if (pollResult.status === 'success') {
const videoUrl = pollResult.result.video_result?.[0]?.url ||
pollResult.result.video_url ||
pollResult.result.url ||
pollResult.result.video;
console.log('Video-URL:', videoUrl);
}
Fehlerbehandlung
Das z-ai-web-dev-sdk kann verschiedene Fehler auslösen. Hier ist ein Muster für die Behandlung:
import ZAI from 'z-ai-web-dev-sdk';
async function safeVideoGeneration(prompt) {
try {
const zai = await ZAI.create();
const task = await zai.video.generations.create({
prompt: prompt,
quality: 'speed'
});
console.log('Videogenerierung gestartet, Aufgaben-ID:', task.id);
return task;
} catch (error) {
if (error.message.includes('Rate Limit')) {
console.error('Ratenlimit erreicht. Bitte später erneut versuchen.');
} else if (error.message.includes('Invalid prompt')) {
console.error('Ungültiger Prompt. Bitte prüfen Sie Ihre Eingabe.');
} else {
console.error('Unerwarteter Fehler bei der Videogenerierung:', error.message);
}
throw error;
}
}
API-Referenz
zai.video.generations.create(options)
Erstellt eine neue Videogenerierungsaufgabe.
Parameter:
| Parameter | Typ | Standard | Beschreibung |
|---|---|---|---|
prompt | string | Erforderlich | Textbeschreibung des Videos |
image_url | string | string[] | Optional | Bevorzugt base64-codierte Bilddaten (z.B. "data:image/png;base64,..."). URLs werden unterstützt, sind aber weniger zuverlässig. Für zwei Bilder ein Array übergeben. |
quality | string | 'speed' | Ausgabequalität: 'speed' oder 'quality' |
with_audio | boolean | false | KI-Audioeffekte generieren |
size | string | '1024x1024' | Videoauflösung (siehe unterstützte Auflösungen oben) |
fps | number | 30 | Bildrate: 30 oder 60 |
duration | number | 5 | Dauer in Sekunden: 5 oder 10 |
model | string | Optional | Zu verwendendes Modell (optional) |
Rückgabe: Ein Aufgabenobjekt mit id, task_status und anderen Feldern.
zai.async.result.query(taskId)
Fragt den Status und das Ergebnis einer asynchronen Aufgabe ab.
Parameter:
| Parameter | Typ | Beschreibung |
|---|---|---|
taskId | string | Die Aufgaben-ID, die von einem vorherigen create-Aufruf zurückgegeben wurde |
Rückgabe: Ein Ergebnisobjekt mit task_status ('PROCESSING', 'SUCCESS', 'FAIL') und möglicherweise video_result, video_url oder andere Felder, wenn erfolgreich.
Vollständiges Beispiel
Ein vollständiges funktionierendes Beispiel finden Sie in der Referenzdatei unter:
{Skill Location}/scripts/video.ts
Dieses Skript demonstriert die Videogenerierung von Anfang bis Ende, einschließlich:
- Initialisierung des SDK
- Aufgabenerstellung mit Text-Prompt
- Polling mit benutzerdefinierten Intervallen
- Ergebnisabruf und -handhabung
- Fehlerbehandlung