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을 입력합니다.
코드 예시
해당 CURL 코드는 다음과 같습니다:응답 예시
요청이 성공하면 API는 해당 동영상 작업의 상태와 결과를 반환합니다. 작업 완료 시 반환 예시는 다음과 같습니다(variants 배열에는 완성본 1개가 포함되어 있습니다):
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: 선택한 언어의 완성본 객체 1개를 포함하며,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를 전달하면 현재 로그인한 실행자의 최근 작업을 가져올 수 있으며(생성 시간 역순), 「내 비디오」 목록 페이지에 사용할 수 있습니다. 기록 목록은 로그인 신원별로 격리됩니다.
Request Body는 다음을 포함합니다:
코드 예시
해당 CURL 코드는 다음과 같습니다:응답 예시
요청이 성공하면 API는 현재 사용자의 과거 작업 목록을 반환합니다: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.
오류 응답 예시
결론
본 문서를 통해 Maestro 작업 조회 API를 사용하여 단일 작업의 상태와 결과를 조회하는 방법 및 현재 사용자의 과거 작업 목록을 가져오는 방법을 이해하셨습니다. 본 문서가 이 API를 더욱 효과적으로 연동하고 사용하는 데 도움이 되기를 바랍니다. 궁금한 점이 있으시면 언제든지 기술 지원팀에 문의해 주세요.관련 인터페이스
- Maestro 동영상 생성 API 연동 안내: 자연어 프롬프트 한 문장으로 자막이 포함된 완성 영상을 자동 생성하며, 제출 후
task_id를 반환하고, 이후 본 인터페이스로 결과를 폴링합니다.

