> ## 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.

# Development Dreamina Tasks

> Dreamina API guide - Ace Data Cloud

## Dreamina Tasks API Integration und Nutzung

Die Dreamina Tasks API wird verwendet, um die Ausführungsergebnisse von digitalen Videoaufgaben, die über die [Dreamina Video Generation API](https://platform.acedata.cloud/documents/dreamina-videos-integration) erstellt wurden, abzufragen. Wenn du beim Generierungs-Interface `callback_url` oder `async: true` übergibst, gibt die API sofort eine `task_id` zurück, mit der du den Status der Aufgabe und die endgültige Video-URL über diese API abfragen kannst. **Diese API ist kostenlos.**

## Antragsprozess

Um die Dreamina API-Serie zu nutzen, musst du zuerst dein API-Token im [Ace Data Cloud Dashboard](https://platform.acedata.cloud/console/applications) abrufen und für später aufbewahren.

Wenn du noch nicht eingeloggt oder registriert bist, wirst du automatisch zur Anmeldeseite weitergeleitet, die dich zur Registrierung und Anmeldung einlädt. Nach Abschluss wirst du automatisch zur aktuellen Seite zurückgeleitet.

**Ein API-Token reicht aus, um auf alle Dienste der Plattform zuzugreifen, es ist nicht erforderlich, für jeden Dienst separat zu beantragen.** Bei der ersten Beantragung erhältst du ein kostenloses Kontingent, um es kostenlos auszuprobieren; wenn das Kontingent erschöpft ist, kannst du im [Dashboard](https://platform.acedata.cloud/console/coin) dein Guthaben aufladen.

## Anfrageparameter

**Request Headers**

* `accept`: Gibt an, dass die Antwort im JSON-Format empfangen werden soll, trage `application/json` ein.
* `authorization`: Der Schlüssel zum Aufrufen der API, im Format `Bearer {token}`.
* `content-type`: Trage `application/json` ein.

**Request Body**

| Parameter | Typ | Pflicht | Beschreibung |
| - | - | - | - |
| `action` | string | Nein | Aktionstyp, `retrieve` (Standard, Einzelabfrage) oder `retrieve_batch` (Batchabfrage) |
| `id` | string | Nein | Die ID der Aufgabe, die abgefragt werden soll (die bei der Erstellung des Videos zurückgegebene `task_id`) |
| `trace_id` | string | Nein | Die Verfolgungs-ID der zu abfragenden Aufgabe, kann anstelle von `id` verwendet werden |
| `ids` | string\[] | Nein | Liste der IDs der Aufgaben für die Batchabfrage, zusammen mit `retrieve_batch` verwenden |

> Bei der Abfrage einer einzelnen Aufgabe muss entweder `id` oder `trace_id` bereitgestellt werden.

## Abfrage einer einzelnen Aufgabe

### CURL

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/dreamina/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve",
  "id": "362b4fed-67bd-11f1-ad11-00163e57d510"
}'
```

### Python

```python theme={null}
import requests

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

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

payload = {
    "action": "retrieve",
    "id": "362b4fed-67bd-11f1-ad11-00163e57d510"
}

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

### Beispielantwort

Nach erfolgreicher Anfrage gibt die API die Details der Aufgabe zurück. `request` ist der Anfrageinhalt, der bei der Erstellung der Aufgabe gesendet wurde, `response` ist der Antwortinhalt nach Abschluss der Aufgabe, wobei `data.video_url` die generierte URL des digitalen Videos ist:

```json theme={null}
{
  "id": "362b4fed-67bd-11f1-ad11-00163e57d510",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "request": {
    "model": "omnihuman-1.5",
    "image_url": "https://cdn.acedata.cloud/4hfydw.jpg",
    "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
  },
  "response": {
    "success": true,
    "data": {
      "task_id": "362b4fed67bd11f1ad1100163e57d510",
      "status": "done",
      "video_url": "https://cdn.acedata.cloud/634d760216.mp4",
      "image_url": "https://cdn.acedata.cloud/4hfydw.jpg",
      "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
    }
  }
}
```

Feldbeschreibung:

* `id`: Die eindeutige ID der Videoerzeugungsaufgabe.
* `trace_id`: Die Verfolgungs-ID dieser Anfrage, die zur Fehlersuche verwendet wird.
* `request`: Der Inhalt der Anfrage, der bei der Erstellung der Aufgabe übermittelt wurde.
* `response`: Der Antwortinhalt nach Abschluss der Aufgabe. Wenn `response.data.status` `done` ist, ist `response.data.video_url` die endgültige Video-URL.
* `created_at`: Erstellungszeit der Aufgabe, Unix-Zeitstempel (Sekunden, Fließkomma).
* `started_at`: Beginn der Ausführung der Aufgabe, Unix-Zeitstempel (Sekunden, Fließkomma).
* `finished_at`: Abschlusszeit der Aufgabe, Unix-Zeitstempel (Sekunden, Fließkomma). Dieses Feld wird nicht zurückgegeben, wenn die Aufgabe nicht abgeschlossen ist.
* `elapsed`: Die für die Ausführung der Aufgabe benötigte Zeit, in Sekunden (Fließkomma, auf 3 Dezimalstellen gerundet). Dieses Feld wird nicht zurückgegeben, wenn die Aufgabe nicht abgeschlossen ist.

> Wenn die Aufgabe noch nicht abgeschlossen ist, kann der `status` einen anderen Wert als `done` haben; wenn die Aufgabe nicht existiert oder noch kein Ergebnis generiert wurde, gibt die API ein leeres Objekt `{}` zurück, bitte später erneut versuchen.

## Batchabfrage von Aufgaben

Setze `action` auf `retrieve_batch` und übergebe ein `ids`-Array:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/dreamina/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve_batch",
  "ids": [
    "362b4fed-67bd-11f1-ad11-00163e57d510",
    "0c0b4d3a-2f1e-4a6b-9c2d-2b3c4d5e6f70"
  ]
}'
```

In der Rückgabe ist `items` ein Array mit den Details der Batchaufgaben (jedes Element hat das gleiche Format wie das Ergebnis einer Einzelabfrage), `count` ist die Anzahl der in dieser Rückgabe enthaltenen Aufgaben.

## Fehlerbehandlung

Wenn beim Aufruf der API ein Fehler auftritt, wird der entsprechende Fehlercode und die Fehlermeldung zurückgegeben:

* `400 bad_request`: Anfragefehler, möglicherweise fehlen notwendige Parameter wie `id` / `trace_id`.
* `401 invalid_token`: Nicht autorisiert, der Autorisierungstoken ist ungültig oder fehlt.
* `429 too_many_requests`: Zu viele Anfragen, die Ratebegrenzung wurde überschritten.
* `500 api_error`: Interner Serverfehler.

### Beispiel für eine Fehlerantwort

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "id or trace_id is required to retrieve a task"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Fazit

Durch dieses Dokument hast du gelernt, wie du die Dreamina Tasks API zur Abfrage von Einzel- oder Batch-Ergebnissen digitaler Videoaufgaben nutzen kannst. In Kombination mit dem Generierungs-Interface im `callback_url` / `async`-Modus kannst du eine stabile Abfrageimplementierung erreichen. Bei Fragen kannst du dich jederzeit an unser technisches Support-Team wenden.


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