Skill zur Videogenerierung
Dieses Skill führt die Implementierung der Videogenerierungsfunktionalität mit dem z-ai-web-dev-sdk-Paket durch und ermöglicht KI-Modellen, Videos aus Textbeschreibungen oder Bildern durch asynchrone Aufgabenverarbeitung zu erstellen.
Skills-Pfad
Skill-Speicherort: {project_path}/skills/video-generation
Dieses Skill befindet sich unter dem oben genannten Pfad in Ihrem Projekt.
Referenzskripte: Beispieltestskripte sind im Verzeichnis {Skill Location}/scripts/ für schnelle Tests und Referenz verfügbar. Siehe {Skill Location}/scripts/video.ts für ein funktionierendes Beispiel.
Überblick
Die Videogenerierung ermöglicht es Ihnen, Anwendungen zu erstellen, die Videoinhalte aus Textprompts oder Bildern mit anpassbaren Parametern wie Auflösung, Bildrate, Dauer und Qualitätseinstellungen generieren können. Die API verwendet ein asynchrones Aufgabenmodell, bei dem Sie eine Aufgabe erstellen und auf Ergebnisse warten.
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, was sie ideal für schnelle Tests und einfache Automatisierung macht.
Basis Text-zu-Video
# Video mit automatischem Polling generieren
z-ai video --prompt "Eine Katze spielt mit einem Ball" --poll
# Verwendung von Kurzoptionen
z-ai video -p "Schöne Landschaft mit Bergen" --poll
Benutzerdefinierte Qualität und Einstellungen
# Qualitätsmodus (speed oder quality)
z-ai video -p "Meereswellen bei Sonnenuntergang" --quality quality --poll
# Benutzerdefinierte Auflösung und Bildrate
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-kodierte 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 etc.), um Decodierungsprobleme zu vermeiden.
# Video aus Einzelbild mit base64 generieren (EMPFOHLEN)
# Konvertieren Sie Ihr Bild mit korrektem MIME-Typ in base64
# Für PNG-Bilder
IMAGE_BASE64=$(base64 -i image.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 photo.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 image.webp)
z-ai video \
--image-url "data:image/webp;base64,${IMAGE_BASE64}" \
--prompt "Die Szene zum Leben erwecken" \
--poll
# Verwendung einer URL (weniger empfohlen, kann Zuverlässigkeitsprobleme haben)
z-ai video \
-i "https://example.com/photo.jpg" \
-p "Dieser Szene Bewegung hinzufügen" \
--poll
Start-Ende-Bild-Modus
WICHTIG: Verwenden Sie für beste Zuverlässigkeit base64-kodierte Bilder anstelle von URLs. Stellen Sie sicher, dass der MIME-Typ zu Ihrem tatsächlichen Bildformat passt.
# Video zwischen zwei Bildern mit base64 generieren (EMPFOHLEN)
# Achten Sie darauf, den korrekten MIME-Typ für jedes Bild zu verwenden
# Beispiel mit PNG-Bildern
START_BASE64=$(base64 -i start.png)
END_BASE64=$(base64 -i end.png)
z-ai video \
--image-url "data:image/png;base64,${START_BASE64},data:image/png;base64,${END_BASE64}" \
--prompt "Sanfter Übergang zwischen Bildern" \
--poll
# Beispiel mit JPEG-Bildern
START_BASE64=$(base64 -i start.jpg)
END_BASE64=$(base64 -i end.jpg)
z-ai video \
--image-url "data:image/jpeg;base64,${START_BASE64},data:image/jpeg;base64,${END_BASE64}" \
--prompt "Sanfter Übergang zwischen Bildern" \
--poll
# Verwendung von URLs (weniger empfohlen)
z-ai video \
--image-url "https://example.com/start.png,https://example.com/end.png" \
--prompt "Sanfter Übergang zwischen Bildern" \
--poll
Mit Audio-Generierung
# Video mit KI-generierten Audioeffekten generieren
z-ai video \
-p "Herannahendes Gewitter" \
--with-audio \
--poll
Ausgabe speichern
# Aufgabenergebnis in JSON-Datei speichern
z-ai video \
-p "Sonnenaufgang über Bergen" \
--poll \
-o video_result.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 erhalten)
z-ai video -p "Abstrakte Kunst-Animation" -o task.json
CLI-Parameter
--prompt, -p <text>: Optional - Textbeschreibung des Videos--image-url, -i <daten>: Optional - Vorzugsweise base64-kodierte Bilddaten (z. B. "data:image/png;base64,iVBORw..."). URLs werden ebenfalls unterstützt, sind aber weniger empfohlen. Für zwei Bilder verwenden Sie kommagetrennte Werte.--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 verwendender Modellname--poll: Optional - Automatisches Polling bis zum Abschluss der Aufgabe--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 deren Status später prüfen:
# Aufgaben-ID aus der ersten Antwort abrufen
z-ai async-result --id "task-id-here" --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 Aufgabenwarteschlangen-Management
- Produktionsanwendungen mit komplexen Workflows
Workflow der Videogenerierung
Die Videogenerierung folgt einem zweistufigen asynchronen Muster:
- Aufgabe erstellen: Videogenerierungsanfrage senden und Aufgaben-ID erhalten
- Ergebnisse abfragen: Aufgabenstatus bis zum Abschluss abfragen und Video-URL abrufen
Implementierung der grundlegenden Videogenerierung
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-kodierte Bilddaten als auch URLs, aber base64-Kodierung wird für eine bessere Zuverlässigkeit und zur Vermeidung netzwerkbezogener Probleme dringend empfohlen.
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 bei unbekannter Erweiterung
}
async function generateVideoFromImage(imagePath, prompt) {
const zai = await ZAI.create();
// Methode 1: Verwendung eines base64-kodierten Bildes (EMPFOHLEN)
// Automatische Erkennung des MIME-Typs aus der Dateierweiterung
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: Verwendung einer URL (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/photo.jpg', // Funktioniert mit JPEG
'Diese Szene mit sanfter Bewegung animieren'
);
const task2 = await generateVideoFromImage(
'./images/graphic.png', // Funktioniert mit PNG
'Dynamische Bewegung hinzufügen'
);
const task3 = await generateVideoFromImage(
'./images/animation.webp', // Funktioniert mit WebP
'Dies zum Leben erwecken'
);
Bild-zu-Video mit Start- und Endbildern
WICHTIG: Für den Schlüsselbild-Modus werden base64-kodierte 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: Verwendung von base64-kodierten Bildern (EMPFOHLEN)
// Automatische Erkennung des MIME-Typs für jedes Bild
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 Schlüsselbildern erstellt:', task.id);
return task;
}
// Methode 2: Verwendung von URLs (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 Schlüsselbildern 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!
'Morphe-Effekt zwischen den 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 dem 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;
}
}
// Beispielverwendung mit Polling
async function waitForVideoWithPolling(taskId, maxAttempts = 60, intervalMs = 5000) {
for (let i = 0; i < maxAttempts; i++) {
const result = await checkTaskStatus(taskId);
if (result.success) {
console.log('Video erfolgreich generiert!');
return result.url;
}
if (result.status === 'failed') {
throw new Error('Videogenerierung fehlgeschlagen');
}
console.log(`Warte auf Fertigstellung... (Versuch ${i + 1}/${maxAttempts})`);
await new Promise(resolve => setTimeout(resolve, intervalMs));
}
throw new Error('Zeitüberschreitung beim Warten auf Videogenerierung');
}
// Ergebnis mit anderen Aufgaben verwalten
async function manageMultipleVideoTasks(taskIds) {
const zai = await ZAI.create();
const results = [];
for (const taskId of taskIds) {
try {
const result = await zai.async.result.query(taskId);
results.push({ taskId, status: result.task_status, data: result });
} catch (error) {
console.error(`Fehler bei Aufgaben-ID ${taskId}:`, error.message);
results.push({ taskId, status: 'error', error: error.message });
}
}
return results;
}
Fehlerbehandlung
Häufige Fehlerszenarien
import ZAI from 'z-ai-web-dev-sdk';
async function generateVideoWithRetry(prompt, maxRetries = 3) {
let lastError = null;
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
console.log(`Versuch ${attempt}/${maxRetries}`);
const result = await generateVideo(prompt);
return result;
} catch (error) {
lastError = error;
console.warn(`Versuch ${attempt} fehlgeschlagen:`, error.message);
if (error.message.includes('rate_limit') || error.message.includes('overloaded')) {
// Exponentielles Backoff
const waitTime = Math.min(1000 * Math.pow(2, attempt), 30000);
console.log(`Warte ${waitTime}ms vor erneutem Versuch...`);
await new Promise(resolve => setTimeout(resolve, waitTime));
} else {
// Nicht wiederholbare Fehler
throw error;
}
}
}
throw lastError;
}
Parameter-Referenz
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
prompt | string | Nein | Textbeschreibung des zu generierenden Videos |
image_url | string/array | Nein | Vorzugsweise base64-kodierte Bilddaten (z. B. "data:image/png;base64,iVBORw..."). URLs werden unterstützt, sind aber weniger empfohlen. Für zwei Bilder verwenden Sie ein Array von Strings. |
quality | string | Nein | Ausgabemodus: speed oder quality |
with_audio | boolean | Nein | KI-generierte Audioeffekte einschließen |
size | string | Nein | Videoauflösung (z. B. "1920x1080"). Siehe unterstützte Auflösungen |
fps | integer | Nein | Bildrate: 30 oder 60 |
duration | integer | Nein | Dauer: 5 oder 10 Sekunden |
model | string | Nein | Zu verwendender Modellname |
Best Practices
- Verwenden Sie base64-kodierte Bilder für Bild-zu-Video, um Netzwerkprobleme zu vermeiden.
- Implementieren Sie Polling mit einem angemessenen Intervall (z. B. 5 Sekunden), um die API nicht zu überlasten.
- Behandeln Sie Timeouts durch Festlegen einer maximalen Anzahl von Polling-Versuchen.
- Validieren Sie den MIME-Typ des base64-Bildes, um Decodierungsfehler zu vermeiden.
- Implementieren Sie Wiederholungslogik mit exponentiellem Backoff für Ratenbegrenzungsfehler.
- Verwenden Sie das SDK im Backend-Code und setzen Sie es niemals clientseitig ein.
Vollständiges Arbeitsbeispiel
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
/**
* Vollständiges Beispiel für Videogenerierung mit Fehlerbehandlung
*/
async function textToVideoExample() {
// Initialisieren
const zai = await ZAI.create();
// Aufgabe erstellen
console.log('Erstelle Videogenerierungsaufgabe...');
const task = await zai.video.generations.create({
prompt: 'Ein Hund rennt durch einen sonnigen Park',
quality: 'quality',
size: '1920x1080',
fps: 30,
duration: 5
});
console.log(`Aufgabe erstellt mit ID: ${task.id}`);
// Auf Fertigstellung warten
console.log('Warte auf Videogenerierung...');
const result = await pollForResult(zai, task.id, 60, 5000);
if (result.success) {
console.log(`Video erfolgreich generiert: ${result.url}`);
return result.url;
} else {
console.error('Videogenerierung fehlgeschlagen');
return null;
}
}
async function pollForResult(zai, taskId, maxPolls, intervalMs) {
for (let i = 0; i < maxPolls; i++) {
const result = await zai.async.result.query(taskId);
if (result.task_status === 'SUCCESS') {
const videoUrl = result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video;
if (videoUrl) {
return { success: true, url: videoUrl };
}
} else if (result.task_status === 'FAIL') {
return { success: false, error: 'Verarbeitung fehlgeschlagen' };
}
console.log(`Status: ${result.task_status} (Versuch ${i + 1}/${maxPolls})`);
await new Promise(resolve => setTimeout(resolve, intervalMs));
}
return { success: false, error: 'Zeitüberschreitung' };
}
// Hauptausführung
(async () => {
try {
const videoUrl = await textToVideoExample();
if (videoUrl) {
console.log('Erfolg! Video-URL:', videoUrl);
}
} catch (error) {
console.error('Ausführung fehlgeschlagen:', error);
}
})();