Maestro 작업 조회 API 연동 안내

Maestro 작업 조회 API의 주요 기능은 Maestro 비디오 생성 API(POST /maestro/videos)가 반환한 작업 ID를 통해 해당 작업의 실행 상태와 최종 결과를 조회하는 것입니다. 본 문서는 Maestro 작업 조회 API의 연동 안내를 상세히 소개합니다. 비디오 생성은 비동기 작업이므로, 제출 후 본 인터페이스를 사용하여 진행 상황과 완성본을 폴링하여 가져와야 하며, 폴링은 무료이고 크레딧을 소모하지 않습니다. POST https://api.acedata.cloud/maestro/tasks

신청 절차

Maestro 작업 조회 API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API Token을 발급받아 보관해 두세요.

아직 로그인하거나 등록하지 않은 경우, 로그인 페이지로 자동 이동하여 등록 및 로그인을 안내하며, 완료 후 현재 페이지로 자동 돌아옵니다. 하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스별로 별도 신청할 필요가 없습니다. 최초 신청 시 무료 할당량이 제공되어 무료로 체험할 수 있으며, 할당량이 부족할 경우 콘솔에서 공통 잔액을 충전할 수 있습니다.

📘 전체 문서: Maestro 작업 조회 API →

단일 작업 조회

비디오 작업 생성 방법은 문서 Maestro 비디오 생성 API를 참고하세요. 여기서는 해당 API가 반환한 작업 ID f57e99c4f60f4373a15517742ce2357d를 예시로 하여 상태와 결과를 조회하는 방법을 시연합니다.

요청 헤더 및 요청 본문 설정

Request Headers에는 다음이 포함됩니다.

accept: 수신할 JSON 형식의 응답 결과를 지정하며, 여기서는 application/json으로 작성합니다.
authorization: API 호출 키이며, 신청 후 직접 드롭다운에서 선택할 수 있습니다.
content-type: 요청 본문의 형식이며, 여기서는 application/json으로 작성합니다.

Request Body에는 다음이 포함됩니다.

필드	유형	필수	설명
`id`	string	단일 작업 조회 시 필수	`POST /maestro/videos`가 반환한 `task_id`
`action`	string	아니요	`retrieve`(기본값, 단일 작업 조회), 이력 목록 조회 시 `retrieve_batch`로 고정

코드 예시

해당 CURL 코드는 다음과 같습니다.

curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "action": "retrieve"
}'

해당 Python 코드는 다음과 같습니다.

import requests

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

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

payload = {
    "id": "f57e99c4f60f4373a15517742ce2357d",
    "action": "retrieve"
}

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

응답 예시

요청이 성공하면 API는 해당 비디오 작업의 상태와 결과를 반환합니다. 작업 완료 시 반환 예시는 다음과 같습니다(각 언어는 하나의 variant에 대응합니다).

{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "started_at": 1769262721.823,
  "finished_at": 1769264698.3,
  "elapsed": 1976.477,
  "status": "succeeded",
  "progress": {
    "percent": 100,
    "stage": "producing",
    "message": "rendering scene 2"
  },
  "request": {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": [
      "zh-cn",
      "en"
    ],
    "aspect": "9:16",
    "duration": 20
  },
  "response": {
    "success": true,
    "data": {
      "variants": [
        {
          "lang": "zh-cn",
          "aspect": "9:16",
          "kind": "video",
          "title": "什么是向量数据库",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001"
        },
        {
          "lang": "en",
          "aspect": "9:16",
          "kind": "video",
          "title": "What is a vector database",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002"
        }
      ],
      "project": {
        "tarball_url": null,
        "outputs": [
          "https://…/zh.mp4",
          "https://…/en.mp4"
        ]
      },
      "percent": 100,
      "stage": "producing",
      "progress": [
        {
          "stage": "producing",
          "message": "rendering scene 2",
          "pct": 60,
          "t": 1750000000
        }
      ]
    }
  }
}

반환 결과의 필드 설명은 다음과 같습니다.

id: 이 비디오 작업의 ID로, 이번 비디오 생성 작업을 고유하게 식별하는 데 사용됩니다.
status: 작업 상태이며, 값은 pending → planning → producing → succeeded(또는 failed)입니다. 작업 완료 여부는 이 최상위 status를 기준으로 합니다.
elapsed: 작업 경과 시간(초)입니다.
progress: 최상위 진행률 객체입니다. 작업 성공 후 percent(0–100)는 100으로 보정됩니다. stage와 message는 AI 디렉터의 가장 최근 진행 이벤트를 반영하므로(따라서 성공 후에도 stage는 producing과 같은 마지막 실행 단계일 수 있음), 진행률 표시줄 표시에 직접 사용할 수 있습니다.
request: 작업 시작 시의 요청 본문입니다.
response: 작업의 반환 정보입니다.
- success: 작업 성공 여부입니다.
- data.variants: 각 언어는 하나의 완성본 객체에 대응하며, lang, aspect, title, output_url(완성본 다운로드 주소) 등을 포함합니다.
- data.project: 전체 프로젝트 산출물이며, tarball_url(프로젝트 패키지)과 outputs(모든 완성본 링크)를 포함합니다.
- data.progress: 단계별로 추가되는 진행 이벤트 배열(append-only 로그)이며, 상세한 실시간 진행 상황을 표시하는 데 사용할 수 있습니다.
created_at: 작업 생성 시간이며, Unix 타임스탬프(초)입니다.
started_at: 작업 실행 시작 시간이며, Unix 타임스탬프(초)입니다. 작업이 아직 시작되지 않은 경우 null입니다.
finished_at: 작업 완료 시간이며, Unix 타임스탬프(초)입니다. 작업이 완료되지 않은 경우 null입니다.

이력 목록 조회

action: retrieve_batch를 전달하면 현재 로그인한 실행자의 최근 작업을 가져올 수 있으며(생성 시간 내림차순), 「내 비디오」 목록 페이지에 사용할 수 있습니다. 이력 목록은 로그인 ID별로 분리됩니다. Request Body에는 다음이 포함됩니다.

필드	유형	필수	설명
`action`	string	예	`retrieve_batch`로 고정
`limit`	int	아니요	반환 개수, 기본값 20; 유효 범위는 1–100
`created_at_max`	int	아니요	해당 Unix 타임스탬프보다 엄격히 이전의 작업만 반환(경계값 제외, 페이지네이션용)
`created_at_min`	int	아니요	해당 Unix 타임스탬프보다 엄격히 이후의 작업만 반환(경계값 제외)

코드 예시

해당 CURL 코드는 다음과 같습니다:

curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve_batch",
  "limit": 20
}'

응답 예시

요청이 성공하면 API는 현재 사용자의 과거 작업 목록을 반환합니다:

{
  "count": 2,
  "items": [
    {
      "id": "f57e99c4f60f4373a15517742ce2357d",
      "started_at": 1769262721.823,
      "finished_at": 1769264698.3,
      "elapsed": 1976.477,
      "status": "succeeded",
      "progress": {
        "percent": 100,
        "stage": "producing",
        "message": "rendering scene 2"
      },
      "request": {
        "prompt": "…",
        "langs": [
          "zh-cn",
          "en"
        ],
        "aspect": "9:16",
        "duration": 20
      },
      "response": {
        "success": true,
        "data": {
          "variants": [
            {
              "lang": "zh-cn",
              "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003"
            }
          ]
        }
      }
    }
  ]
}

반환 결과의 필드 설명은 다음과 같습니다:

count: 현재 로그인한 실행자에게 표시되는 전체 작업 수이며, 시간 조건 또는 limit의 영향을 받지 않습니다.
items: 시간 조건 및 limit으로 필터링된 작업 배열이며, 생성 시간 내림차순으로 정렬됩니다; 각 요소의 형식은 「단일 작업 조회」의 반환 결과와 일치합니다.

폴링 권장 사항

동영상 생성에는 비교적 긴 시간이 소요되므로, status는 pending → planning → producing → succeeded(또는 failed)를 거칩니다. status가 succeeded 또는 failed로 변경될 때까지 5–10초마다 한 번씩 폴링하는 것을 권장합니다. 최상위 progress.percent를 활용하여 실시간 진행률 표시줄을 표시할 수 있습니다. 이 인터페이스 폴링은 무료이며, 크레딧을 소모하지 않습니다.

오류 처리

API 호출 시 오류가 발생하면 API는 해당 오류 코드와 정보를 반환합니다. 예를 들면:

401 invalid_token: Unauthorized, invalid or missing authorization token.
404 not_found: Task not found, the given task_id does not exist.
429 too_many_requests: Too many requests, you have exceeded the rate limit.
500 api_error: Internal server error, something went wrong on the server.

오류 응답 예시

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

결론

본 문서를 통해 Maestro 작업 조회 API를 사용하여 단일 작업의 상태와 결과를 조회하고, 현재 사용자의 과거 작업 목록을 가져오는 방법을 이해하셨습니다. 본 문서가 이 API를 더 효과적으로 연동하고 사용하는 데 도움이 되기를 바랍니다. 궁금한 사항이 있으면 언제든지 기술 지원 팀에 문의해 주세요.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

Coding

추가 가이드

Maestro 작업 조회 API 연동 안내

신청 절차

단일 작업 조회

요청 헤더 및 요청 본문 설정

코드 예시

응답 예시

이력 목록 조회

코드 예시

응답 예시

폴링 권장 사항

오류 처리

오류 응답 예시

결론

관련 인터페이스

​신청 절차

​단일 작업 조회

​요청 헤더 및 요청 본문 설정

​코드 예시

​응답 예시

​이력 목록 조회

​코드 예시

​응답 예시

​폴링 권장 사항

​오류 처리

​오류 응답 예시

​결론

​관련 인터페이스

신청 절차

단일 작업 조회

요청 헤더 및 요청 본문 설정

코드 예시

응답 예시

이력 목록 조회

코드 예시

응답 예시

폴링 권장 사항

오류 처리

오류 응답 예시

결론

관련 인터페이스