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

# Maestro 작업 조회 API 연동 안내

> Maestro AI Video Studio API guide - Ace Data Cloud

Maestro 작업 조회 API의 주요 기능은 [Maestro 비디오 생성 API](/ko/guides/maestro/maestro_videos)(`POST /maestro/videos`)가 반환한 작업 ID를 통해 해당 작업의 실행 상태와 최종 결과를 조회하는 것입니다.

본 문서는 Maestro 작업 조회 API의 연동 안내를 상세히 소개합니다. 비디오 생성은 비동기 작업이므로, 제출 후 본 인터페이스를 사용하여 진행 상황과 완성본을 폴링하여 가져와야 하며, **폴링은 무료이고 크레딧을 소모하지 않습니다.**

`POST https://api.acedata.cloud/maestro/tasks`

## 신청 절차

Maestro 작업 조회 API를 사용하려면 먼저 [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)에서 API Token을 발급받아 보관해 두세요.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

아직 로그인하거나 등록하지 않은 경우, 로그인 페이지로 자동 이동하여 등록 및 로그인을 안내하며, 완료 후 현재 페이지로 자동 돌아옵니다.

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

> 📘 전체 문서: [Maestro 작업 조회 API →](https://platform.acedata.cloud/documents/maestro-tasks)

## 단일 작업 조회

비디오 작업 생성 방법은 문서 [Maestro 비디오 생성 API](/ko/guides/maestro/maestro_videos)를 참고하세요. 여기서는 해당 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 코드는 다음과 같습니다.

```bash theme={null}
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 코드는 다음과 같습니다.

```python theme={null}
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`에 대응합니다).

```json theme={null}
{
  "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 코드는 다음과 같습니다:

```bash theme={null}
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는 현재 사용자의 과거 작업 목록을 반환합니다:

```json theme={null}
{
  "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.

### 오류 응답 예시

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

## 결론

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

## 관련 인터페이스

* [Maestro 동영상 생성 API 연동 설명](/ko/guides/maestro/maestro_videos): 한 문장의 자연어 프롬프트로 자막이 포함된 완성 영상을 자동 생성하며, 제출 후 `task_id`를 반환하고, 이어서 본 인터페이스로 결과를 폴링합니다.


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