Schritt 1: API-Schlüssel besorgen und Client vorbereiten
Besorge dir einen Freebeat-API-Schlüssel und wähle einen MCP-kompatiblen Client. Behandle den Schlüssel als vertraulich: Übernimm ihn nicht in die Versionsverwaltung und lege ihn nicht im clientseitigen Code offen.
Daran erkennst du den Erfolg: Dem MCP-Server steht der Schlüssel über eine sichere lokale Konfiguration zur Verfügung.
Häufiger Fehler, den du vermeiden solltest: Füge einen echten API-Schlüssel niemals in ein geteiltes Codebeispiel oder ein öffentliches Repository ein.
Schritt 2: Freebeat-MCP-Server konfigurieren
Füge den Freebeat-Servereintrag zur Konfiguration deines MCP-Clients hinzu. Ersetze den Beispielschlüssel durch deine eigenen Zugangsdaten und behalte die JSON-Struktur bei:
{
"mcpServers": {
"freebeat": {
"command": "npx",
"args": ["-y", "freebeat-mcp"],
"env": {
"FREEBEAT_API_KEY": "your-api-key-here"
}
}
}
}
Daran erkennst du den Erfolg: Dein MCP-Client kann den Server starten und seine Freebeat-Tools bereitstellen.
Häufiger Fehler, den du vermeiden solltest: Ein falsch geschriebener Variablenname oder ungültiges JSON kann den Start des Servers verhindern.
Schritt 3: Verfügbare Videomodelle ermitteln
Rufe list_models mit type: "video" auf. Sieh dir die zurückgegebenen Einträge und Felder wie model_id, model, display_name, Befehle und Einschränkungen an.
Daran erkennst du den Erfolg: Du hast eine aktuelle Modellkennung oder einen API-Modellschlüssel aus der zurückgegebenen Liste.
Häufiger Fehler, den du vermeiden solltest: Verwende keinen angenommenen Modellnamen fest im Code, wenn sich die verfügbare Liste ändern kann.
Schritt 4: Anforderungen des ausgewählten Modells prüfen
Rufe get_model_help mit der numerischen ID des ausgewählten Modells oder dem API-Modellschlüssel auf. Prüfe die unterstützten Dauern, Auflösungen, Seitenverhältnisse und Optionen für die Audiogenerierung, bevor du die Anfrage zusammenstellst.
Daran erkennst du den Erfolg: Du weißt, welche Parameter für dieses spezielle Modell erforderlich, optional und zulässig sind.
Häufiger Fehler, den du vermeiden solltest: Die Anforderungen eines Modells gelten möglicherweise nicht für ein anderes. Übernimm daher keine Einstellungen, ohne sie zu überprüfen.
Schritt 5: Text-zu-Video-Anfrage absenden
Rufe generate_video mit einem unterstützten Modell und einem nicht leeren, auf 1–2.000 Zeichen gekürzten Prompt auf. Gib duration und resolution an, wenn das Modell sie als erforderlich ausweist. Verwende aspect_ratio oder generate_audio nur, wenn diese Parameter unterstützt werden. Die Modelleinschränkungen werden vor dem Absenden einer Anfrage überprüft.
Daran erkennst du den Erfolg: Das Tool akzeptiert deine Anfrage und gibt eine Batch-Kennung für die asynchrone Verarbeitung zurück.
Häufiger Fehler, den du vermeiden solltest: Sende keine nicht unterstützten Dauer-, Auflösungs- oder Audioeinstellungen, die auf Annahmen beruhen.
Schritt 6: Batch abfragen, bis ein Endstatus erreicht ist
Rufe get_task_status mit der zurückgegebenen batch_id als task_id auf. Frage den Status so lange ab, bis die Antwort completed oder failed meldet. Ältere Backends können aktuelle Statuswerte auch in Großbuchstaben zurückgeben.
Daran erkennst du den Erfolg: Du kannst zwischen einer laufenden Aufgabe, einem abgeschlossenen Ergebnis und einer fehlgeschlagenen Aufgabe unterscheiden.
Häufiger Fehler, den du vermeiden solltest: Verwechsle die anfängliche Batch-Antwort nicht mit dem fertigen Videoergebnis.
Schritt 7: Fertige Video-URL abrufen und verwenden
Wenn der Status abgeschlossen ist, prüfe die items der Antwort und rufe die video_url des relevanten Elements ab. Ein einzelnes Element kann abgefragt werden, indem du optional serial_no übergibst. Open-RPC-Batchergebnisse geben ihre URLs direkt im Aufgabenstatus zurück; für diese Batches wird get_task_result nicht verwendet.
Daran erkennst du den Erfolg: Deine Anwendung erhält eine verwendbare Video-URL aus dem abgeschlossenen Batch-Element.
Häufiger Fehler, den du vermeiden solltest: Prüfe Status- und Fehlerfelder des Elements, bevor du eine fehlende URL als erfolgreiches Ergebnis behandelst.