> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Maestro-Aufgabenabfrage-API Integrationsanleitung

> Maestro AI Video Studio API guide - Ace Data Cloud

Die Hauptfunktion der Maestro-Aufgabenabfrage-API besteht darin, über die von der [Maestro-Videogenerierungs-API](/de/guides/maestro/maestro_videos) (`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](https://platform.acedata.cloud/console/applications) Ihr API-Token ab und bewahren Sie es zur späteren Verwendung auf.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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](https://platform.acedata.cloud/console/coin) allgemeines Guthaben aufladen.

> 📘 Vollständige Dokumentation: [Maestro-Aufgabenabfrage-API →](https://platform.acedata.cloud/documents/maestro-tasks)

## Abfrage einer einzelnen Aufgabe

Informationen zum Erstellen einer Videoaufgabe finden Sie in der Dokumentation zur [Maestro-Videogenerierungs-API](/de/guides/maestro/maestro_videos). 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:

```bash theme={null}
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:

```python theme={null}
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`):

```json theme={null}
{
  "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:

```bash theme={null}
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:

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

## Verwandte Schnittstellen

* [Anleitung zur Anbindung der Maestro-Videoerstellungs-API](/de/guides/maestro/maestro_videos): Mit einem Prompt in natürlicher Sprache automatisch ein fertiges Video mit Untertiteln erstellen; nach der Übermittlung wird `task_id` zurückgegeben, anschließend können die Ergebnisse mit dieser Schnittstelle abgefragt werden.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.