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

## Intégration et utilisation de l'API Dreamina Tasks

L'API Dreamina Tasks est utilisée pour interroger les résultats d'exécution des tâches vidéo de personnages numériques créées par l'[API de génération de vidéos Dreamina](https://platform.acedata.cloud/documents/dreamina-videos-integration). Lorsque vous passez `callback_url` ou `async: true` dans l'interface de génération, l'interface renvoie immédiatement un `task_id`, que vous pouvez utiliser pour interroger l'état de la tâche et l'adresse vidéo finale via cette interface en fonction de `task_id` ou `trace_id`. **Cette interface est gratuite.**

## Processus de demande

Pour utiliser la série d'API Dreamina, commencez par obtenir votre API Token sur le [tableau de bord Ace Data Cloud](https://platform.acedata.cloud/console/applications) pour le garder en réserve.

Si vous n'êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inviter à vous inscrire et à vous connecter, après quoi vous serez automatiquement renvoyé à la page actuelle.

**Un seul API Token suffit pour appeler tous les services de la plateforme, sans avoir besoin de demander séparément pour chaque service.** La première demande vous donnera un quota gratuit pour une expérience sans frais ; lorsque le quota est insuffisant, vous pouvez recharger le solde général sur le [tableau de bord](https://platform.acedata.cloud/console/coin).

## Paramètres de demande

**En-têtes de demande**

* `accept` : spécifie que la réponse doit être au format JSON, remplissez `application/json`.
* `authorization` : clé d'API pour appeler l'API, au format `Bearer {token}`.
* `content-type` : remplissez `application/json`.

**Corps de la demande**

| Paramètre | Type | Obligatoire | Description |
| - | - | - | - |
| `action` | string | Non | Type d'opération, `retrieve` (par défaut, interroger un seul) ou `retrieve_batch` (interrogation par lot) |
| `id` | string | Non | ID de la tâche à interroger (le `task_id` retourné lors de la création de la vidéo) |
| `trace_id` | string | Non | ID de suivi de la tâche à interroger, peut remplacer `id` |
| `ids` | string\[] | Non | Liste des ID de tâches pour l'interrogation par lot, à utiliser avec `retrieve_batch` |

> Lors de l'interrogation d'une seule tâche, `id` et `trace_id` doivent en fournir au moins un.

## Interroger une seule tâche

### 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)
```

### Exemple de réponse

Après une demande réussie, l'API renvoie les détails de la tâche. `request` est le corps de la demande lors de la création de la tâche, `response` est le corps de la réponse après l'achèvement de la tâche, où `data.video_url` est l'adresse de la vidéo de personnage numérique générée :

```json theme={null}
{
  "id": "362b4fed-67bd-11f1-ad11-00163e57d510",
  "started_at": 1769262721.823,
  "finished_at": 1769262769.123,
  "elapsed": 47.3,
  "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"
    }
  }
}
```

Description des champs :

* `id` : ID unique de la tâche de génération de vidéo.
* `trace_id` : ID de suivi de cette demande, utilisé pour le dépannage.
* `request` : Contenu de la demande soumis lors de la création de la tâche.
* `response` : Contenu de la réponse renvoyé après l'achèvement de la tâche. Lorsque `response.data.status` est `done`, `response.data.video_url` est l'adresse vidéo finale.
* `created_at` : Heure de création de la tâche, horodatage Unix (secondes, flottant).
* `started_at` : Heure de début d'exécution de la tâche, horodatage Unix (secondes, flottant).
* `finished_at` : Heure d'achèvement de la tâche, horodatage Unix (secondes, flottant). Ce champ n'est pas renvoyé si la tâche n'est pas terminée.
* `elapsed` : Temps d'exécution de la tâche, en secondes (flottant, avec 3 décimales). Ce champ n'est pas renvoyé si la tâche n'est pas terminée.

> Si la tâche n'est pas encore terminée, `status` peut ne pas être dans l'état `done` ; si la tâche n'existe pas ou n'a pas encore généré de résultats, l'interface renverra un objet vide `{}`, veuillez réessayer plus tard.

## Interrogation par lot de tâches

Définissez `action` sur `retrieve_batch` et passez un tableau `ids` :

```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"
  ]
}'
```

Dans le résultat retourné, `items` est un tableau de détails des tâches par lot (chaque élément a le même format que le résultat d'une requête unique), `count` est le nombre de tâches retournées cette fois.

## Gestion des erreurs

Lors de l'appel de l'API, si une erreur se produit, un code d'erreur et un message correspondants seront renvoyés :

* `400 bad_request` : Erreur de demande, il peut manquer des paramètres nécessaires comme `id` / `trace_id`.
* `401 invalid_token` : Non autorisé, le jeton d'autorisation est invalide ou manquant.
* `429 too_many_requests` : Trop de demandes, dépassement de la limite de taux.
* `500 api_error` : Erreur interne du serveur.

### Exemple de réponse d'erreur

```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"
}
```

## Conclusion

Grâce à ce document, vous avez compris comment utiliser l'API Dreamina Tasks pour interroger les résultats des tâches vidéo de personnages numériques, qu'il s'agisse d'une seule ou d'un lot. En combinaison avec le mode asynchrone `callback_url` / `async` de l'interface de génération, vous pouvez réaliser un tirage stable. Si vous avez des questions, n'hésitez pas à contacter notre équipe de support technique.


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