¶ Using the Dreamina Tasks API

The Dreamina Tasks API retrieves the result of a digital-human video task created by the Dreamina Video Generation API. When you pass callback_url or async: true to the generation endpoint, it returns a task_id immediately; you can then poll this endpoint by task_id or trace_id for the task status and the final video URL. This endpoint is free.

¶ Getting started

To use the Dreamina APIs, first get your API Token from the Ace Data Cloud console.

If you are not logged in or registered, you will be redirected to sign in and brought back automatically.

A single API Token works across every service on the platform — no need to apply per service. New accounts receive free credits to try it out; top up your shared balance in the console when needed.

¶ Request parameters

Request Headers

• accept: response format, set to application/json.
• authorization: your API key, formatted as Bearer {token}.
• content-type: set to application/json.

Request Body

Parameter	Type	Required	Description
action	string	No	retrieve (default, single task) or retrieve_batch (multiple tasks)
id	string	No	Task ID to query (the task_id returned when creating the video)
trace_id	string	No	Trace ID of the task; can be used instead of id
ids	string[]	No	List of task IDs for batch retrieval, used with retrieve_batch

When retrieving a single task, provide at least one of id or trace_id.

¶ Retrieve a single task

¶ CURL

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

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)

¶ Response example

On success, the API returns the task details. request is the body you sent when creating the task, and response is the body returned once the task finishes — its data.video_url is the generated talking-photo video:

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

Field reference:

• id: unique ID of this video generation task.
• trace_id: trace ID of the request, useful for troubleshooting.
• request: the request body submitted when creating the task.
• response: the response body returned once finished. When response.data.status is done, response.data.video_url is the final video URL.

If the task has not finished, status may be a non-done value; if the task does not exist or has no result yet, the endpoint returns an empty object {} — retry shortly.

¶ Batch retrieval

Set action to retrieve_batch and pass an ids array:

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

The response contains items (an array of task details, each identical in shape to a single retrieval) and count (the number of tasks returned).

¶ Error handling

When an error occurs, the API returns a matching error code and message:

• 400 bad_request: bad request, possibly missing id / trace_id.
• 401 invalid_token: unauthorized, invalid or missing token.
• 429 too_many_requests: too many requests, rate limit exceeded.
• 500 api_error: internal server error.

¶ Error response example

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

¶ Conclusion

You now know how to use the Dreamina Tasks API to retrieve single or batch digital-human video tasks. Combined with the callback_url / async modes of the generation endpoint, this enables reliable polling. If you have any questions, feel free to contact our support team.