POST /maestro/videos) zurückgegebene Aufgaben-ID den Ausführungsstatus und das Endergebnis dieser Aufgabe abzufragen.
Dieses Dokument stellt die Anleitung zur Integration der Maestro-Aufgabenabfrage-API ausführlich vor. Da die Videogenerierung eine asynchrone Aufgabe ist, müssen Sie nach der Übermittlung diese Schnittstelle zur Abfrage des Fortschritts und des fertigen Videos verwenden; die Abfrage ist kostenlos und verbraucht keine Punkte.
POST https://api.acedata.cloud/maestro/tasks
Antragsprozess
Um die Maestro-Aufgabenabfrage-API zu verwenden, rufen Sie zunächst in der Ace Data Cloud-Konsole Ihren API-Token ab und bewahren Sie ihn als Reserve auf.
Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Nach Abschluss kehren Sie automatisch zur aktuellen Seite zurück.
Ein API-Token kann alle Plattformdienste aufrufen; Sie müssen nicht für jeden Dienst separat einen Antrag stellen. Beim ersten Antrag wird ein kostenloses Guthaben verschenkt, sodass Sie den Dienst kostenlos testen können; bei unzureichendem Guthaben können Sie in der Konsole allgemeines Guthaben aufladen.
📘 Vollständige Dokumentation: Maestro-Aufgabenabfrage-API →
Einzelne Aufgabe abfragen
Informationen dazu, wie Sie eine Videoaufgabe erstellen, finden Sie in der Dokumentation zur Maestro-Videogenerierungs-API. Wir verwenden eine von ihr zurückgegebene Aufgaben-ID als Beispiel:f57e99c4f60f4373a15517742ce2357d, um zu demonstrieren, wie ihr Status und Ergebnis abgefragt werden.
Anfrage-Header und Anfrage-Body festlegen
Request Headers umfassen:accept: Gibt an, dass ein Antwortergebnis im JSON-Format empfangen wird; hier wirdapplication/jsoneingetragen.authorization: Der Schlüssel zum Aufrufen der API, der nach dem Antrag direkt über ein Dropdown ausgewählt werden kann.content-type: Das Format des Anfrage-Bodys; hier wirdapplication/jsoneingetragen.
Codebeispiel
Der entsprechende CURL-Code lautet:Antwortbeispiel
Nach erfolgreicher Anfrage gibt die API den Status und die Ergebnisse dieser Videoaufgabe zurück. Ein Beispiel für die Rückgabe nach Abschluss der Aufgabe lautet wie folgt (das Arrayvariants enthält ein fertiges Video):
id: Die ID dieser Videoaufgabe, die zur eindeutigen Identifizierung dieses Videoerstellungsauftrags dient.status: Aufgabenstatus. Mögliche Werte sindpending → planning → producing → succeeded(oderfailed). Ob die Aufgabe abgeschlossen ist, richtet sich nach dem oberstenstatus.elapsed: Bisherige Ausführungszeit der Aufgabe (Sekunden).progress: Fortschrittsobjekt der obersten Ebene.percent(0–100) beträgt nach erfolgreichem Abschluss der Aufgabe 100;stageundmessagespiegeln das neueste Fortschrittsereignis des KI-Regisseurs wider (daher kannstagenach Erfolg weiterhin die letzte Ausführungsphase wieproducingsein) und können direkt zur Anzeige eines Fortschrittsbalkens verwendet werden.request: Der Anfragekörper beim Starten der Aufgabe.response: Rückgabeinformationen der Aufgabe.success: Gibt an, ob die Aufgabe erfolgreich war.data.variants: Enthält ein Objekt für das fertige Video in der ausgewählten Sprache, einschließlichlang,aspect,title,output_url(Download-Adresse des fertigen Videos) usw.data.project: Das gesamte Projektartefakt, einschließlichtarball_url(Projektpaket) undoutputs(Link zum fertigen Video).data.progress: Ein Array von nach Phasen hinzugefügten Fortschrittsereignissen (Append-only-Protokoll), das zur Anzeige detaillierter Echtzeitfortschritte verwendet werden kann.
created_at: Erstellungszeit der Aufgabe als Unix-Zeitstempel (Sekunden).started_at: Startzeit der Aufgabenausführung als Unix-Zeitstempel (Sekunden). Vor dem Start der Aufgabe ist der Wert null.finished_at: Zeitpunkt der Aufgabenfertigstellung, Unix-Zeitstempel (Sekunden). Bei nicht abgeschlossenen Aufgaben null.
Verlaufsliste abfragen
Durch Übergabe vonaction: retrieve_batch können Sie die zuletzt ausgeführten Aufgaben des aktuell angemeldeten Ausführenden abrufen (absteigend nach Erstellungszeit), was für die Listenseite „Meine Videos“ verwendet werden kann. Die Verlaufsliste ist nach Anmeldeidentität getrennt.
Request Body umfasst:
Codebeispiel
Der entsprechende CURL-Code lautet:Antwortbeispiel
Nach erfolgreicher Anfrage gibt die API die Liste der historischen Aufgaben des aktuellen Benutzers zurück:count: Die Gesamtzahl der für den aktuell angemeldeten Ausführenden sichtbaren Aufgaben, unabhängig von Zeitbedingungen oderlimit.items: Ein Aufgabenarray, das anhand der Zeitbedingungen undlimitgefiltert und in absteigender Reihenfolge nach Erstellungszeit sortiert ist; das Format jedes Elements stimmt mit dem Rückgabeergebnis von „Eine einzelne Aufgabe abfragen“ überein.
Empfehlungen zum Polling
Da die Videoproduktion relativ lange dauert, durchläuftstatus die Zustände pending → planning → producing → succeeded (oder failed). Es wird empfohlen, alle 5–10 Sekunden zu pollen, bis status zu succeeded oder failed wird. Mithilfe von progress.percent auf oberster Ebene kann ein Echtzeit-Fortschrittsbalken angezeigt werden. Das Polling dieser Schnittstelle ist kostenlos und verbraucht keine Credits.
Fehlerbehandlung
Wenn beim Aufrufen der API ein Fehler auftritt, gibt die API den entsprechenden Fehlercode und die entsprechende Information zurück. Zum Beispiel:401 invalid_token: Unauthorized, invalid or missing authorization token.404 not_found: Task not found, the given task_id does not exist.429 too_many_requests: Too many requests, you have exceeded the rate limit.500 api_error: Internal server error, something went wrong on the server.
Beispiel für Fehlerantwort
Fazit
Durch dieses Dokument haben Sie bereits erfahren, wie Sie die Maestro-Aufgabenabfrage-API verwenden können, um den Status und die Ergebnisse einer einzelnen Aufgabe abzufragen sowie die Liste der historischen Aufgaben des aktuellen Benutzers abzurufen. Wir hoffen, dass dieses Dokument Ihnen dabei hilft, diese API besser anzubinden und zu verwenden. Falls Sie Fragen haben, kontaktieren Sie jederzeit unser technisches Supportteam.Verwandte Schnittstellen
- Anleitung zur Anbindung der Maestro-API für Videogenerierung: Produziert mithilfe eines Prompts in natürlicher Sprache automatisch ein fertiges Video mit Untertiteln, gibt nach der Übermittlung
task_idzurück und verwendet anschließend diese Schnittstelle zum Abrufen der Ergebnisse per Polling.

