> ## 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의 연동 및 사용

Dreamina Tasks API는 [Dreamina Video Generation API](https://platform.acedata.cloud/documents/dreamina-videos-integration)에서 생성된 디지털 사람 비디오 작업의 실행 결과를 조회하는 데 사용됩니다. 생성 인터페이스에 `callback_url` 또는 `async: true`를 전달하면, 인터페이스는 즉시 `task_id`를 반환하며, 이 인터페이스를 통해 `task_id` 또는 `trace_id`로 작업 상태와 최종 비디오 주소를 폴링할 수 있습니다. **이 인터페이스는 무료입니다.**

## 신청 절차

Dreamina 시리즈 API를 사용하려면, 먼저 [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)에서 API Token을 받아야 하며, 이를 보관해 두십시오.

로그인 또는 등록하지 않은 경우, 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 초대합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다.

**하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스에 대해 별도로 신청할 필요가 없습니다.** 처음 신청 시 무료 할당량이 제공되어 무료로 체험할 수 있으며, 할당량이 부족할 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 일반 잔액을 충전할 수 있습니다.

## 요청 매개변수

**Request Headers**

* `accept`：JSON 형식의 응답 결과를 수신하도록 지정하며, `application/json`을 입력합니다.
* `authorization`：API 호출의 키로, 형식은 `Bearer {token}`입니다.
* `content-type`：`application/json`을 입력합니다.

**Request Body**

| 매개변수 | 유형 | 필수 | 설명 |
| - | - | - | - |
| `action` | string | 아니오 | 작업 유형, `retrieve`(기본값, 단일 조회) 또는 `retrieve_batch`(배치 조회) |
| `id` | string | 아니오 | 조회할 작업 ID(비디오 생성 시 반환된 `task_id`) |
| `trace_id` | string | 아니오 | 조회할 작업의 추적 ID, `id` 대신 사용할 수 있습니다. |
| `ids` | string\[] | 아니오 | 배치 조회의 작업 ID 목록, `retrieve_batch`와 함께 사용합니다. |

> 단일 작업을 조회할 때, `id`와 `trace_id` 중 하나는 반드시 제공해야 합니다.

## 단일 작업 조회

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

### 응답 예시

요청이 성공하면, API는 해당 작업의 세부 정보를 반환합니다. `request`는 작업 생성 시의 요청 본문이며, `response`는 작업 완료 후의 응답 본문으로, 여기서 `data.video_url`은 생성된 디지털 사람 비디오 주소입니다:

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

필드 설명:

* `id`：이번 비디오 생성 작업의 고유 ID입니다.
* `trace_id`：이번 요청의 추적 ID로, 문제 해결에 사용됩니다.
* `request`：작업 생성 시 제출한 요청 내용입니다.
* `response`：작업 완료 후 반환된 응답 내용입니다. `response.data.status`가 `done`일 때, `response.data.video_url`이 최종 비디오 주소입니다.
* `created_at`：작업 생성 시간, Unix 타임스탬프(초, 부동 소수점).
* `started_at`：작업 시작 실행 시간, Unix 타임스탬프(초, 부동 소수점).
* `finished_at`：작업 완료 시간, Unix 타임스탬프(초, 부동 소수점). 작업이 완료되지 않은 경우 이 필드는 반환되지 않습니다.
* `elapsed`：작업 실행 소요 시간, 단위는 초(부동 소수점, 소수점 3자리). 작업이 완료되지 않은 경우 이 필드는 반환되지 않습니다.

> 작업이 아직 완료되지 않은 경우, `status`는 `done`이 아닐 수 있습니다; 작업이 존재하지 않거나 결과가 생성되지 않은 경우, 인터페이스는 빈 객체 `{}`를 반환하므로 나중에 다시 시도하십시오.

## 배치 작업 조회

`action`을 `retrieve_batch`로 설정하고 `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"
  ]
}'
```

반환 결과에서 `items`는 배치 작업 세부 정보 배열(각 요소는 단일 조회 결과 형식과 일치)이며, `count`는 이번에 반환된 작업 수입니다.

## 오류 처리

API 호출 중 오류가 발생하면 해당 오류 코드와 정보가 반환됩니다:

* `400 bad_request`：요청 오류, `id` / `trace_id` 등 필수 매개변수가 누락되었을 수 있습니다.
* `401 invalid_token`：권한 없음, 인증 토큰이 유효하지 않거나 누락되었습니다.
* `429 too_many_requests`：요청이 너무 많음, 속도 제한을 초과했습니다.
* `500 api_error`：서버 내부 오류입니다.

### 오류 응답 예시

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

## 결론

이 문서를 통해 Dreamina Tasks API를 사용하여 단일 또는 배치 디지털 사람 비디오 작업의 결과를 조회하는 방법을 이해하게 되었습니다. 생성 인터페이스의 `callback_url` / `async` 비동기 모드와 함께 사용하면 안정적인 폴링을 구현할 수 있습니다. 질문이 있는 경우 언제든지 기술 지원 팀에 문의해 주십시오.


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