Zum Hauptinhalt springen
Maestro ist eine Agent-native Schnittstelle zur Videoproduktion: Sie beschreiben das gewünschte Video mit einem natürlichen Sprach-prompt (optional können Sie mit file_urls Referenzbilder / -videos / -audios anhängen), und ein kopfloser „KI-Regisseur“ erledigt automatisch Themenauswahl, Drehbucherstellung, Bildgenerierung, Vertonung, Hintergrundmusik, Komposition und Rendering. Schließlich wird ein fertiges Video mit Untertiteln erstellt und auf das CDN hochgeladen. Dieser Artikel stellt die Anleitung zur Integration der Maestro-API für die Videogenerierung ausführlich vor, um Ihnen zu helfen, diese API schnell zu integrieren und ihre Funktionen vollständig zu nutzen. Dies ist eine asynchrone Aufgabe-Schnittstelle: Nach der Übermittlung wird sofort task_id zurückgegeben. Anschließend erhalten Sie die Ergebnisse durch Abfragen über die Maestro-Aufgabenabfrage-API (POST /maestro/tasks) (Abfragen sind kostenlos und werden nicht berechnet). Um auf einem vorhandenen Video weiter zu iterieren, können Sie action: remix / edit / extend zusammen mit ref_task_id verwenden.

Antragsprozess

Um die Maestro-API für die Videogenerierung zu verwenden, rufen Sie zunächst in der Ace Data Cloud-Konsole Ihren API-Token ab und bewahren Sie ihn als Reserve auf. Falls Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet und zur Registrierung und Anmeldung aufgefordert. Nach Abschluss kehren Sie automatisch zu dieser Seite zurück. Ein API-Token kann alle Dienste der Plattform aufrufen; Sie müssen ihn nicht für jeden Dienst separat beantragen. Bei der ersten Beantragung erhalten Sie ein kostenloses Kontingent, das Sie kostenlos ausprobieren können; bei unzureichendem Kontingent können Sie in der Konsole ein allgemeines Guthaben aufladen.
📘 Vollständige Dokumentation: Maestro-API für die Videogenerierung →

Grundlegende Verwendung

POST https://api.acedata.cloud/maestro/videos Für die grundlegendste Nutzung muss lediglich eine natürliche Sprachbeschreibung in prompt übergeben werden. Der KI-Regisseur entscheidet automatisch über Skript, Bildmaterial, Vertonung und Schnitt. Hier sehen wir uns zunächst die erforderlichen Request-Header und den Request-Body an. Request-Header umfassen:
  • accept: Das gewünschte Format der Antwort. Hier application/json eintragen, also das JSON-Format.
  • authorization: Der Schlüssel zum Aufrufen der API. Nach der Beantragung kann er direkt über die Auswahlliste ausgewählt werden.
  • content-type: Das Format des Request-Bodys. Hier application/json eintragen.
Request-Body umfasst hauptsächlich:
  • prompt: Beschreiben Sie das zu erstellende Video in natürlicher Sprache (Thema, darzustellende Inhalte, Stil, Zielgruppe).
  • langs: Array der Ausgabesprache; pro Anfrage nur eine Sprache übergeben, z. B. ["zh-cn"]. Standardmäßig ["zh-cn"].
  • aspect: Seitenverhältnis, 9:16 (Standard) / 16:9 / 1:1.
  • duration: Ziellänge (Sekunden), standardmäßig 30.
Alle Felder des Request-Bodys sind in der folgenden Tabelle aufgeführt: Im Folgenden wird dies anhand eines konkreten Beispiels demonstriert. Angenommen, wir möchten ein 20-sekündiges wissenschaftliches Kurzvideo auf Chinesisch im Hochformat erstellen. Der entsprechende CURL-Code lautet:
Der entsprechende Python-Code lautet:
Nach dem Klicken auf „Ausführen“ ist sofort ein Ergebnis verfügbar, wie unten gezeigt:
Die Felder des Rückgabeergebnisses werden im Folgenden erläutert:
  • success: Ob diese Aufgabe erfolgreich übermittelt wurde.
  • task_id: Die ID dieser Videogenerierungsaufgabe. Verwenden Sie sie anschließend, um die Ergebnisse über die Maestro-API zur Aufgabenabfrage abzufragen.
  • trace_id: Die Tracking-ID dieser Anfrage, die bei Problemen dem technischen Support zur Fehleranalyse bereitgestellt werden kann.
Da die Videoproduktion viel Zeit in Anspruch nimmt, gibt die Schnittstelle hier sofort task_id zurück und wartet nicht, bis das Video gerendert wurde. Anschließend muss task_id verwendet werden, um das Ergebnis abzufragen. Details finden Sie im Abschnitt „Ergebnis abrufen“.

Videotyp und Stil angeben (scenario / style)

Wenn scenario nicht übergeben wird, erfolgt die automatische Bestimmung durch die KI (entspricht auto); wenn das Video auf einen bestimmten Typ festgelegt werden soll, übergeben Sie ihn explizit. Um beispielsweise ein Kurzdrama im Hochformat zu erstellen, können Sie Folgendes angeben:
  • scenario: Videotyp, hier auf drama gesetzt (Kurzdrama mit Charakteren + Dialogen).
  • style: Visueller Stil, hier auf cinematic gesetzt (filmische Qualität).
Der CURL-Code für das Ausfüllbeispiel lautet wie folgt:
Gängige Kombinationsmöglichkeiten:
  • Erklär-Kurzfilm: scenario: "narrated".
  • Automatische Untertitel: scenario: "captions", das Quellvideo muss über file_urls übergeben werden.
  • Digitaler Mensch / Sprechvideo: scenario: "avatar", ein Porträtbild muss über file_urls übergeben werden.
  • Kurzdrama: scenario: "drama" (Charaktere + Dialoge).
  • style ist eine Voreinstellung für den visuellen Stil (z. B. modern / neon / luxury), die den Typ nicht verändert und nur den visuellen Eindruck beeinflusst.
  • voice wird verwendet, um die Stimmfarbe der Erzählstimme anzugeben (z. B. warm-female / deep-male), unabhängig von der Sprache und sprachübergreifend verwendbar.
Das Rückgabeergebnis entspricht der „Grundlegenden Verwendung“ und gibt ebenfalls sofort task_id zurück.

Sprache des fertigen Videos

Eine Aufgabe liefert nur ein fertiges Video in einer Sprache. langs darf nur einen Sprachcode enthalten, z. B. ["zh-cn"] oder ["en"]; bei mehreren Sprachen wird 400 zurückgegeben. Wenn Videos in unterschiedlichen Sprachen benötigt werden, erstellen Sie bitte separate Aufgaben. Die Sprachauswahl verändert den Preis pro Sekunde nicht.

Auf bestehenden Videos iterieren (remix / edit / extend)

Durch Übergabe von action und ref_task_id der vorherigen Aufgabe können Sie inkrementelle Änderungen auf Grundlage des ursprünglichen Projekts vornehmen (z. B. „Den Titel der zweiten Szene ändern“, „Eine andere Synchronstimme verwenden“, „Das Gesamtbild abdunkeln“). Kleine Änderungen sind schnell, bei großen Änderungen wird neu erstellt:
  • remix: Auf Grundlage der ursprünglichen Videostruktur neu interpretieren (Thema beibehalten, Darstellung anpassen).
  • edit: Bestimmte lokale Bereiche detailliert bearbeiten (z. B. Titel, Synchronstimme oder Farbgebung ändern).
  • extend: Inhalte auf Grundlage des ursprünglichen Videos erweitern.
Auch das Rückgabeergebnis gibt sofort eine neue task_id zurück, mit der das iterierte fertige Video durch Abfrage abgerufen werden kann.

Ergebnis abrufen

Da die Videoproduktion relativ zeitaufwendig ist, gibt diese Schnittstelle nach der Übermittlung sofort task_id zurück. Sie müssen diese verwenden, um die Ergebnisse über die Maestro-Aufgabenabfrage-API abzufragen:
Nach Abschluss der Aufgabe wird eine Information zum fertigen Video zurückgegeben (im Array variants). status durchläuft pending → planning → producing → succeeded (oder failed), die Abfrage ist kostenlos und verbraucht keine Credits. Das vollständige Antwortformat und die Abfrage der Verlaufsliste finden Sie in der Integrationsanleitung für die Maestro-Aufgabenabfrage-API.

Abrechnung

Nach erfolgreicher Aufgabe erfolgt die Abrechnung nach der tatsächlichen Dauer des gelieferten fertigen Videos; bei einem Fehlschlag fallen keine Kosten an. Die Abrechnungsdauer wird in ganzen Sekunden berechnet und überschreitet nicht die angeforderte Dauer; wenn die Dauer des fertigen Videos nicht gelesen werden kann, wird auf die angeforderte Dauer zurückgegriffen. Die Übermittlung der Aufgabe selbst wird nicht separat berechnet, die Abfrage über /maestro/tasks ist kostenlos.
Alle Szenarien, Aktionen und Sprachen verwenden denselben Preis, ohne Szenario-Multiplikator oder Sprachaufschlag. Jede Aufgabe liefert nur ein fertiges Video in einer Sprache. Die angeforderte Zieldauer unterstützt 5–300 Sekunden, einheitliche Ausgabe in 1080p / 30fps.

Fehlerbehandlung

Wenn beim Aufrufen der API ein Fehler auftritt, gibt die API den entsprechenden Fehlercode und die entsprechende Information zurück. Zum Beispiel:
  • 400 invalid_request: Ungültige Anfrage, möglicherweise aufgrund eines fehlenden prompt oder ungültiger Parameter.
  • 401 invalid_token: Nicht autorisiert, ungültiges oder fehlendes Autorisierungstoken.
  • 403 forbidden: Verboten, unzureichendes Guthaben oder unzureichender Zugriff.
  • 429 too_many_requests: Zu viele Anfragen, Sie haben das Ratenlimit überschritten.
  • 500 api_error: Interner Serverfehler, auf dem Server ist ein Fehler aufgetreten.

Beispiel für eine Fehlerantwort

Fazit

Durch dieses Dokument haben Sie bereits erfahren, wie Sie die Maestro-Videogenerierungs-API verwenden: Mit nur einem natürlichsprachlichen prompt können Skript, Materialien, Vertonung, Hintergrundmusik, Schnitt, Untertitel und Rendering des fertigen Videos automatisch abgeschlossen werden. Zudem werden die Angabe von Videotyp, Stil, Stimmfarbe und Sprache des fertigen Videos sowie die Iteration auf bestehenden Videos unterstützt. Wir hoffen, dass dieses Dokument Ihnen hilft, diese API besser zu integrieren und zu verwenden. Bei Fragen können Sie sich jederzeit an unser technisches Supportteam wenden.

Verwandte Schnittstellen