Development Dreamina Tasks

Dreamina Tasks API의 연동 및 사용

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

신청 절차

Dreamina 시리즈 API를 사용하려면, 먼저 Ace Data Cloud 콘솔에서 API Token을 받아야 하며, 이를 보관해 두십시오. 로그인 또는 등록하지 않은 경우, 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 초대합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다. 하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스에 대해 별도로 신청할 필요가 없습니다. 처음 신청 시 무료 할당량이 제공되어 무료로 체험할 수 있으며, 할당량이 부족할 경우 콘솔에서 일반 잔액을 충전할 수 있습니다.

요청 매개변수

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

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)

응답 예시

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

{
  "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 배열을 전달합니다:

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：서버 내부 오류입니다.

오류 응답 예시

{
  "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 비동기 모드와 함께 사용하면 안정적인 폴링을 구현할 수 있습니다. 질문이 있는 경우 언제든지 기술 지원 팀에 문의해 주십시오.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

Coding

추가 가이드

Development Dreamina Tasks

Dreamina Tasks API의 연동 및 사용

신청 절차

요청 매개변수

단일 작업 조회

CURL

Python

응답 예시

배치 작업 조회

오류 처리

오류 응답 예시

결론

​Dreamina Tasks API의 연동 및 사용

​신청 절차

​요청 매개변수

​단일 작업 조회

​CURL

​Python

​응답 예시

​배치 작업 조회

​오류 처리

​오류 응답 예시

​결론

Dreamina Tasks API의 연동 및 사용

신청 절차

요청 매개변수

단일 작업 조회

CURL

Python

응답 예시

배치 작업 조회

오류 처리

오류 응답 예시

결론