Zum Hauptinhalt springen
Die Hauptfunktion der Maestro-Aufgabenabfrage-API besteht darin, über die von der Maestro-Videogenerierungs-API (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 wird application/json eingetragen.
  • 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 wird application/json eingetragen.
Request Body umfasst:

Codebeispiel

Der entsprechende CURL-Code lautet:
Der entsprechende Python-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 Array variants enthält ein fertiges Video):
Die Felder des Rückgabeergebnisses werden im Folgenden erläutert:
  • id: Die ID dieser Videoaufgabe, die zur eindeutigen Identifizierung dieses Videoerstellungsauftrags dient.
  • status: Aufgabenstatus. Mögliche Werte sind pending → planning → producing → succeeded (oder failed). Ob die Aufgabe abgeschlossen ist, richtet sich nach dem obersten status.
  • elapsed: Bisherige Ausführungszeit der Aufgabe (Sekunden).
  • progress: Fortschrittsobjekt der obersten Ebene. percent (0–100) beträgt nach erfolgreichem Abschluss der Aufgabe 100; stage und message spiegeln das neueste Fortschrittsereignis des KI-Regisseurs wider (daher kann stage nach Erfolg weiterhin die letzte Ausführungsphase wie producing sein) 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ßlich lang, aspect, title, output_url (Download-Adresse des fertigen Videos) usw.
    • data.project: Das gesamte Projektartefakt, einschließlich tarball_url (Projektpaket) und outputs (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 von action: 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:
Die Felder des Rückgabeergebnisses werden wie folgt beschrieben:
  • count: Die Gesamtzahl der für den aktuell angemeldeten Ausführenden sichtbaren Aufgaben, unabhängig von Zeitbedingungen oder limit.
  • items: Ein Aufgabenarray, das anhand der Zeitbedingungen und limit gefiltert 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äuft status 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