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. Hierapplication/jsoneintragen, 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. Hierapplication/jsoneintragen.
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.
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:
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.
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)
Wennscenario 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 aufdramagesetzt (Kurzdrama mit Charakteren + Dialogen).style: Visueller Stil, hier aufcinematicgesetzt (filmische Qualität).
- Erklär-Kurzfilm:
scenario: "narrated". - Automatische Untertitel:
scenario: "captions", das Quellvideo muss überfile_urlsübergeben werden. - Digitaler Mensch / Sprechvideo:
scenario: "avatar", ein Porträtbild muss überfile_urlsübergeben werden. - Kurzdrama:
scenario: "drama"(Charaktere + Dialoge). styleist eine Voreinstellung für den visuellen Stil (z. B.modern/neon/luxury), die den Typ nicht verändert und nur den visuellen Eindruck beeinflusst.voicewird verwendet, um die Stimmfarbe der Erzählstimme anzugeben (z. B.warm-female/deep-male), unabhängig von der Sprache und sprachübergreifend verwendbar.
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 vonaction 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.
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 soforttask_id zurück. Sie müssen diese verwenden, um die Ergebnisse über die Maestro-Aufgabenabfrage-API abzufragen:
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.
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 fehlendenpromptoder 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ürlichsprachlichenprompt 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
- Integrationsanleitung für die Maestro-Aufgabenabfrage-API: Verwenden Sie die von
POST /maestro/videoszurückgegebenetask_id, um Aufgabenstatus und Ergebnisse abzufragen oder die Liste historischer Aufgaben abzurufen (Abfrage kostenlos).

