Maestro-Aufgabenabfrage-API Integrationsanleitung

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 Integrationsanleitung für die Maestro-Aufgabenabfrage-API detailliert vor. Da die Videogenerierung eine asynchrone Aufgabe ist, müssen nach der Übermittlung über diese Schnittstelle Fortschritt und fertiges Video per Polling abgerufen werden. Polling ist kostenlos und verbraucht keine Credits. 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 Ihr API-Token ab und bewahren Sie es zur späteren Verwendung auf.

Falls Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Nach Abschluss kehren Sie automatisch zu dieser Seite zurück. Ein API-Token kann alle Dienste der Plattform aufrufen; es ist nicht erforderlich, jeden Dienst separat zu 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 allgemeines Guthaben aufladen.

📘 Vollständige Dokumentation: Maestro-Aufgabenabfrage-API →

Abfrage einer einzelnen Aufgabe

Informationen zum Erstellen einer Videoaufgabe 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 Antwortergebnisse im JSON-Format empfangen werden; hier wird application/json eingetragen.
authorization: Der Schlüssel zum Aufrufen der API, der nach der Beantragung direkt aus einer Dropdown-Liste ausgewählt werden kann.
content-type: Das Format des Anfrage-Body; hier wird application/json eingetragen.

Request Body umfasst:

Feld	Typ	Erforderlich bei	Beschreibung
`id`	string	Bei Abfrage einer einzelnen Aufgabe erforderlich	Die von `POST /maestro/videos` zurückgegebene `task_id`
`action`	string	Nein	`retrieve` (Standard, Abfrage einer einzelnen Aufgabe); bei Abfrage der Verlaufsliste fest auf `retrieve_batch` gesetzt

Codebeispiele

Der entsprechende CURL-Code lautet wie folgt:

curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "action": "retrieve"
}'

Der entsprechende Python-Code lautet wie folgt:

import requests

url = "https://api.acedata.cloud/maestro/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "id": "f57e99c4f60f4373a15517742ce2357d",
    "action": "retrieve"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Antwortbeispiel

Nach erfolgreicher Anfrage gibt die API den Status und das Ergebnis dieser Videoaufgabe zurück. Ein Rückgabebeispiel bei abgeschlossener Aufgabe lautet wie folgt (jede Sprache entspricht einer variant):

{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "started_at": 1769262721.823,
  "finished_at": 1769264698.3,
  "elapsed": 1976.477,
  "status": "succeeded",
  "progress": {
    "percent": 100,
    "stage": "producing",
    "message": "rendering scene 2"
  },
  "request": {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": [
      "zh-cn",
      "en"
    ],
    "aspect": "9:16",
    "duration": 20
  },
  "response": {
    "success": true,
    "data": {
      "variants": [
        {
          "lang": "zh-cn",
          "aspect": "9:16",
          "kind": "video",
          "title": "什么是向量数据库",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001"
        },
        {
          "lang": "en",
          "aspect": "9:16",
          "kind": "video",
          "title": "What is a vector database",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002"
        }
      ],
      "project": {
        "tarball_url": null,
        "outputs": [
          "https://…/zh.mp4",
          "https://…/en.mp4"
        ]
      },
      "percent": 100,
      "stage": "producing",
      "progress": [
        {
          "stage": "producing",
          "message": "rendering scene 2",
          "pct": 60,
          "t": 1750000000
        }
      ]
    }
  }
}

Die Felder des Rückgabeergebnisses werden wie folgt vorgestellt:

id: Die ID dieser Videoaufgabe, die zur eindeutigen Kennzeichnung dieser Videogenerierungsaufgabe verwendet wird.
status: Aufgabenstatus mit den Werten pending → planning → producing → succeeded (oder failed). Ob die Aufgabe abgeschlossen ist, richtet sich nach diesem übergeordneten status.
elapsed: Bisherige Dauer der Aufgabe (Sekunden).
progress: Übergeordnetes Fortschrittsobjekt; percent (0–100) wird nach erfolgreicher Aufgabe auf 100 abgesichert; stage und message spiegeln das zuletzt vom KI-Regisseur gemeldete Fortschrittsereignis 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 Anfrage-Body beim Starten der Aufgabe.
response: Die Rückgabeinformationen der Aufgabe.
- success: Ob die Aufgabe erfolgreich war.
- data.variants: Jede Sprache entspricht einem fertigen Videoobjekt, das unter anderem lang, aspect, title und output_url (Downloadadresse des fertigen Videos) enthält.
- data.project: Das gesamte Projektartefakt, einschließlich tarball_url (Projektpaket) und outputs (alle Links zu fertigen Videos).
- data.progress: Ein Array von nach Phasen hinzugefügten Fortschrittsereignissen (Append-only-Log), das zur Anzeige detaillierter Echtzeitfortschritte verwendet werden kann.
created_at: Erstellungszeit der Aufgabe, Unix-Zeitstempel (Sekunden).
started_at: Startzeit der Aufgabenausführung, Unix-Zeitstempel (Sekunden). null, wenn die Aufgabe noch nicht gestartet wurde.
finished_at: Abschlusszeit der Aufgabe, Unix-Zeitstempel (Sekunden). null, wenn die Aufgabe noch nicht abgeschlossen wurde.

Abfrage der Verlaufsliste

Durch Übergabe von action: retrieve_batch können die zuletzt vom aktuell angemeldeten Ausführenden erstellten Aufgaben abgerufen werden (absteigend nach Erstellungszeit), was für die Listenseite „Meine Videos“ verwendet werden kann. Die Verlaufsliste ist nach Anmeldeidentität getrennt. Request Body umfasst:

Feld	Typ	Erforderlich	Beschreibung
`action`	string	Ja	Fest auf `retrieve_batch` gesetzt
`limit`	int	Nein	Anzahl der zurückgegebenen Einträge, standardmäßig 20; gültiger Bereich ist 1–100
`created_at_max`	int	Nein	Gibt nur Aufgaben zurück, die strikt vor diesem Unix-Zeitstempel liegen (Grenzwert nicht eingeschlossen, für Paginierung)
`created_at_min`	int	Nein	Gibt nur Aufgaben zurück, die strikt nach diesem Unix-Zeitstempel liegen (Grenzwert nicht eingeschlossen)

Codebeispiel

Der entsprechende CURL-Code lautet wie folgt:

curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve_batch",
  "limit": 20
}'

Antwortbeispiel

Nach erfolgreicher Anfrage gibt die API die Liste der historischen Aufgaben des aktuellen Benutzers zurück:

{
  "count": 2,
  "items": [
    {
      "id": "f57e99c4f60f4373a15517742ce2357d",
      "started_at": 1769262721.823,
      "finished_at": 1769264698.3,
      "elapsed": 1976.477,
      "status": "succeeded",
      "progress": {
        "percent": 100,
        "stage": "producing",
        "message": "rendering scene 2"
      },
      "request": {
        "prompt": "…",
        "langs": [
          "zh-cn",
          "en"
        ],
        "aspect": "9:16",
        "duration": 20
      },
      "response": {
        "success": true,
        "data": {
          "variants": [
            {
              "lang": "zh-cn",
              "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003"
            }
          ]
        }
      }
    }
  ]
}

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: Das durch Zeitbedingungen und limit gefilterte Aufgabenarray, in absteigender Reihenfolge der Erstellungszeit; das Format jedes Elements stimmt mit dem Rückgabeergebnis von „Einzelne Aufgabe abfragen“ überein.

Empfehlungen zum Polling

Da die Videoproduktion länger dauert, durchläuft status pending → planning → producing → succeeded (oder failed). Es wird empfohlen, alle 5–10 Sekunden eine Abfrage durchzuführen, bis status zu succeeded oder failed wird. Mit dem obersten progress.percent 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: Nicht autorisiert, ungültiges oder fehlendes Autorisierungstoken.
404 not_found: Aufgabe nicht gefunden, die angegebene task_id existiert nicht.
429 too_many_requests: Zu viele Anfragen, Sie haben das Ratenlimit überschritten.
500 api_error: Interner Serverfehler, auf dem Server ist etwas schiefgelaufen.

Beispiel für Fehlerantwort

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Fazit

Durch dieses Dokument haben Sie erfahren, wie Sie mit der Maestro-Aufgabenabfrage-API den Status und die Ergebnisse einer einzelnen Aufgabe abfragen sowie die historische Aufgabenliste des aktuellen Benutzers abrufen können. Wir hoffen, dass dieses Dokument Ihnen hilft, diese API besser anzubinden und zu verwenden. Bei Fragen kontaktieren Sie bitte jederzeit unser technisches Supportteam.

Erste Schritte

KI Chat

KI Bild

KI Video

KI Audio

Web & Daten

CAPTCHA

Identität

Coding

Weitere Anleitungen

Maestro-Aufgabenabfrage-API Integrationsanleitung

Antragsprozess

Abfrage einer einzelnen Aufgabe

Anfrage-Header und Anfrage-Body festlegen

Codebeispiele

Antwortbeispiel

Abfrage der Verlaufsliste

Codebeispiel

Antwortbeispiel

Empfehlungen zum Polling

Fehlerbehandlung

Beispiel für Fehlerantwort

Fazit

Verwandte Schnittstellen

​Antragsprozess

​Abfrage einer einzelnen Aufgabe

​Anfrage-Header und Anfrage-Body festlegen

​Codebeispiele

​Antwortbeispiel

​Abfrage der Verlaufsliste

​Codebeispiel

​Antwortbeispiel

​Empfehlungen zum Polling

​Fehlerbehandlung

​Beispiel für Fehlerantwort

​Fazit

​Verwandte Schnittstellen

Antragsprozess

Abfrage einer einzelnen Aufgabe

Anfrage-Header und Anfrage-Body festlegen

Codebeispiele

Antwortbeispiel

Abfrage der Verlaufsliste

Codebeispiel

Antwortbeispiel

Empfehlungen zum Polling

Fehlerbehandlung

Beispiel für Fehlerantwort

Fazit

Verwandte Schnittstellen