Fähigkeit zur Videogenerierung
Diese Fähigkeit leitet die Implementierung der Videogenerierungsfunktionalität mithilfe des z-ai-web-dev-sdk-Pakets an und ermöglicht KI-Modellen, Videos aus Textbeschreibungen oder Bildern durch asynchrone Aufgabenverarbeitung zu erstellen.
Skills-Pfad
Fähigkeiten-Standort: {project_path}/skills/video-generation
Diese Fähigkeit befindet sich unter dem obigen 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.
Übersicht
Die Videogenerierung ermöglicht es Ihnen, Anwendungen zu erstellen, die Videoinhalte aus Textaufforderungen oder Bildern generieren können, mit anpassbaren Parametern wie Auflösung, Bildrate, Dauer und Qualitätseinstellungen. Die API verwendet ein asynchrones Aufgabenmodell, bei dem Sie eine Aufgabe erstellen und auf Ergebnisse warten.
WICHTIG: z-ai-web-dev-sdk MUSS ausschließlich 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 Abfrage automatisch und ist ideal für schnelle Tests und einfache Automatisierung.
Grundlegende Text-zu-Video
# Video mit automatischer Abfrage generieren
z-ai video --prompt "Eine Katze spielt mit einem Ball" --poll
# Mit kurzen Optionen
z-ai video -p "Wunderschö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 FPS
z-ai video \
-p "Stadtzeitraffer" \
--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 usw.), um Dekodierungsprobleme zu vermeiden.
# Video aus einem einzelnen Bild mit base64 generieren (EMPFOHLEN)
# Konvertieren Sie Ihr Bild mit dem korrekten 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
# URL verwenden (weniger empfohlen, kann Zuverlässigkeitsprobleme haben)
z-ai video \
-i "https://example.com/photo.jpg" \
-p "Bewegung zu dieser Szene hinzufügen" \
--poll
First-Last-Frame-Modus
WICHTIG: Verwenden Sie für beste Zuverlässigkeit base64-kodierte Bilder anstelle von URLs. Stellen Sie sicher, dass der MIME-Typ mit Ihrem tatsächlichen Bildformat übereinstimmt.
# Video zwischen zwei Frames mit base64 generieren (EMPFOHLEN)
# Verwenden Sie den korrekten MIME-Typ für jedes Bild
# 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 den Frames" \
--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 den Frames" \
--poll
# URLs verwenden (weniger empfohlen)
z-ai video \
--image-url "https://example.com/start.png,https://example.com/end.png" \
--prompt "Sanfter Übergang zwischen den Frames" \
--poll
Mit Audio-Generierung
# Video mit KI-generierten Audioeffekten generieren
z-ai video \
-p "Herannahender Gewittersturm" \
--with-audio \
--poll
Ausgabe speichern
# Aufgabenergebnis in einer JSON-Datei speichern
z-ai video \
-p "Sonnenaufgang über den Bergen" \
--poll \
-o video_result.json
Benutzerdefinierte Abfrageparameter
# Abfrageverhalten anpassen
z-ai video \
-p "Tanzender Roboter" \
--poll \
--poll-interval 10 \
--max-polls 30
# Aufgabe ohne Abfrage erstellen (Aufgaben-ID abrufen)
z-ai video -p "Abstrakte Kunst-Animation" -o task.json
CLI-Parameter
--prompt, -p <text>: Optional - Textbeschreibung des Videos--image-url, -i <data>: Optional - Vorzugweise base64-kodierte Bilddaten (z. B. "data:image/png;base64,iVBORw..."). URLs werden ebenfalls unterstützt, sind aber weniger empfohlen. Für zwei Bilder durch Kommas getrennte 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 verwendender Modellname--poll: Optional - Automatisch abfragen, bis die Aufgabe abgeschlossen ist--poll-interval <sekunden>: Optional - Abfrageintervall (Standard: 5)--max-polls <anzahl>: Optional - Maximale Anzahl von Abfrageversuchen (Standard: 60)--output, -o <pfad>: Optional - Ausgabedateipfad (JSON-Format)
Unterstützte Auflösungen
1024x1024768x1344864x11521344x7681152x8641440x720720x14401920x1080(und andere Standardauflösungen)
Aufgabenstatus später überprüfen
Wenn Sie eine Aufgabe ohne --poll erstellen, können Sie ihren 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 Aufforderungen und Einstellungen
SDK verwenden für:
- Batch-Videogenerierung mit benutzerdefinierter Logik
- Integration in Webanwendungen
- Benutzerdefinierte Aufgabenwarteschlangenverwaltung
- 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
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(`Abfrage ${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 dringend empfohlen für eine bessere Zuverlässigkeit und um netzwerkbezogene Probleme zu vermeiden.
Kritisch: Passen Sie den MIME-Typ in Ihrem base64-Daten-URI immer an das tatsächliche Bildformat an, um Dekodierungsfehler 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'; // Standardmäßig JPEG, wenn unbekannt
}
async function generateVideoFromImage(imagePath, prompt) {
const zai = await ZAI.create();
// Methode 1: base64-kodiertes Bild verwenden (EMPFOHLEN)
// 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/photo.jpg', // Funktioniert mit JPEG
'Animieren Sie diese Szene mit sanfter Bewegung'
);
const task2 = await generateVideoFromImage(
'./images/graphic.png', // Funktioniert mit PNG
'Dynamische Bewegung hinzufügen'
);
const task3 = await generateVideoFromImage(
'./images/animation.webp', // Funktioniert mit WebP
'Erwecken Sie dies zum Leben'
);
Bild-zu-Video mit Start- und End-Frames
WICHTIG: Im 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: base64-kodierte Bilder verwenden (EMPFOHLEN)
// 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 Schlüsselbildern 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 Schlüsselbildern erstellt:', task.id);
return task;
}
// Verwendungsbeispiele mit verschiedenen Formaten
const task1 = await generateVideoWithKeyframes(
'./frames/start.jpg', // JPEG-Startframe
'./frames/end.jpg', // JPEG-Endframe
'Sanfter Übergang zwischen diesen Szenen'
);
const task2 = await generateVideoWithKeyframes(
'./frames/start.png', // PNG-Startframe
'./frames/end.webp', // WebP-Endframe - verschiedene Formate funktionieren!
'Morphing-Effekt zwischen Bildern'
);
Asynchrone Ergebnisverwaltung
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;
}
}
Fortgeschrittene Videogenerierung
Video mit Audio generieren
import ZAI from 'z-ai-web-dev-sdk';
async function generateVideoWithAudio(prompt) {
const zai = await ZAI.create();
const task = await zai.video.generations.create({
prompt: prompt,
quality: 'quality',
with_audio: true, // KI-Audioeffekte generieren
size: '1920x1080',
fps: 30,
duration: 10
});
console.log('Video-Generierungsaufgabe mit Audio erstellt:', task.id);
return task;
}
Mit verschiedenen Auflösungen und Einstellungen
import ZAI from 'z-ai-web-dev-sdk';
async function generateCustomVideo(prompt, settings = {}) {
const zai = await ZAI.create();
const task = await zai.video.generations.create({
prompt: prompt,
quality: settings.quality || 'speed',
with_audio: settings.with_audio || false,
size: settings.size || '1024x1024',
fps: settings.fps || 30,
duration: settings.duration || 5,
model: settings.model // Optionales spezifisches Modell
});
return task;
}
// Verwendungsbeispiele
const portraitVideo = await generateCustomVideo(
'Porträt einer Person',
{ size: '768x1344', quality: 'quality' }
);
const landscapeVideo = await generateCustomVideo(
'Landschaftsaufnahme',
{ size: '1344x768', quality: 'quality', fps: 60 }
);
Stapelverarbeitung
import ZAI from 'z-ai-web-dev-sdk';
async function batchGenerateVideos(prompts, options = {}) {
const zai = await ZAI.create();
const tasks = [];
for (const prompt of prompts) {
const task = await zai.video.generations.create({
prompt: prompt,
quality: options.quality || 'speed',
with_audio: options.with_audio || false,
size: options.size || '1024x1024',
fps: options.fps || 30,
duration: options.duration || 5
});
tasks.push(task);
console.log(`Aufgabe für "${prompt}" erstellt:`, task.id);
}
return tasks; // Jede Aufgabe einzeln abfragen
}
// Verwendung
const prompts = [
'Ein Hund rennt am Strand entlang',
'Eine Stadtlandschaft bei Nacht',
'Zeitraffer von Wolken'
];
const tasks = await batchGenerateVideos(prompts, { quality: 'quality' });
Fehlerbehandlung und Wiederholungslogik
import ZAI from 'z-ai-web-dev-sdk';
async function generateVideoWithRetry(prompt, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
const zai = await ZAI.create();
const task = await zai.video.generations.create({
prompt: prompt,
quality: 'speed',
with_audio: false,
size: '1920x1080',
fps: 30,
duration: 5
});
// Ergebnisse mit Zeitüberschreitung abfragen
const result = await pollWithTimeout(task.id, 120000); // 2 Minuten Zeitüberschreitung
return result;
} catch (error) {
console.log(`Versuch ${attempt} fehlgeschlagen: ${error.message}`);
if (attempt === maxRetries) {
throw new Error(`Videogenerierung nach ${maxRetries} Versuchen fehlgeschlagen`);
}
await new Promise(resolve => setTimeout(resolve, 2000 * attempt));
}
}
}
async function pollWithTimeout(taskId, timeoutMs) {
const startTime = Date.now();
const zai = await ZAI.create();
while (Date.now() - startTime < timeoutMs) {
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;
return { success: true, url: videoUrl };
}
if (result.task_status === 'FAIL') {
return { success: false, status: 'failed' };
}
await new Promise(resolve => setTimeout(resolve, 5000));
}
throw new Error('Zeitüberschreitung beim Abfragen des Aufgabenstatus');
}
// Verwendung
const result = await generateVideoWithRetry('Animierte Visualisierung von Datenströmen');
Best Practices
- Bildformate: Verwenden Sie base64-kodierte Bilder mit korrektem MIME-Typ für eine bessere Zuverlässigkeit und um Netzwerkprobleme zu vermeiden.
- Abfrage-Intervall: Verwenden Sie ein angemessenes Abfrage-Intervall (5 Sekunden Standard), um die API-Rate nicht zu überschreiten.
- Fehlerbehandlung: Implementieren Sie eine Wiederholungslogik für vorübergehende Fehler.
- Aufgabenverwaltung: Speichern Sie Aufgaben-IDs für eine spätere Statusüberprüfung.
- Leistung: Für Stapelverarbeitung erstellen Sie Aufgaben parallel und fragen Sie Ergebnisse asynchron ab.
- Sicherheit: Verwenden Sie das SDK nur im Backend; setzen Sie API-Schlüssel niemals im clientseitigen Code ein.
Fehlerbehebung
Häufige Probleme
- Aufgabe fehlgeschlagen: Überprüfen Sie die Prompteingabe und stellen Sie sicher, dass die Parameter gültig sind.
- Zeitüberschreitung: Erhöhen Sie maxPolls oder pollInterval für komplexe Videogenerierungen.
- Ungültige Bilddaten: Stellen Sie sicher, dass base64-Daten korrekt kodiert sind und den richtigen MIME-Typ haben.
- Netzwerkfehler: Verwenden Sie base64-kodierte Bilder anstelle von URLs.
Debugging
// Detaillierte Aufgabeninformationen protokollieren
async function debugTask(taskId) {
const zai = await ZAI.create();
const result = await zai.async.result.query(taskId);
console.log('Vollständige Aufgabenantwort:', JSON.stringify(result, null, 2));
return result;
}