Skip to main content
Maestro는 Agent 원주율 비디오 제작 인터페이스입니다: 자연어 prompt로 원하는 비디오를 설명하면 (선택적으로 file_urls로 참조 이미지 / 비디오 / 오디오를 첨부할 수 있습니다), 무헤드의 “AI 감독”이 자동으로 주제를 정하고, 스크립트를 작성하고, 화면을 생성하고, 더빙하고, 배경 음악을 추가하고, 합성 및 렌더링을 수행하여 최종적으로 자막이 포함된 완성된 영상을 생성하고 CDN에 업로드합니다. 본 문서에서는 Maestro 비디오 생성 API의 연동 설명을 자세히 소개하여, 귀하가 신속하게 통합하고 API의 기능을 충분히 활용할 수 있도록 돕겠습니다. 이것은 비동기 작업 인터페이스입니다: 제출 후 즉시 task_id가 반환되며, 이후 Maestro 작업 조회 API (POST /maestro/tasks)를 통해 결과를 폴링하여 가져옵니다 (폴링은 무료로 청구되지 않음). 기존 비디오에서 계속 반복 작업을 하려면 action: remix / edit / extend와 함께 ref_task_id를 사용할 수 있습니다.

신청 절차

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

기본 사용법

POST https://api.acedata.cloud/maestro/videos 가장 기본적인 사용법은 자연어 prompt를 전달하는 것만으로, AI 감독이 자동으로 스크립트, 화면, 더빙 및 편집을 결정합니다. 여기서는 설정해야 할 요청 헤더와 요청 본체를 살펴보겠습니다. Request Headers에는 다음이 포함됩니다:
  • accept: 어떤 형식의 응답 결과를 받고 싶은지, 여기서는 application/json으로 작성하여 JSON 형식으로 설정합니다.
  • authorization: API 호출을 위한 키, 신청 후 바로 드롭다운에서 선택할 수 있습니다.
  • content-type: 요청 본체의 형식, 여기서는 application/json으로 작성합니다.
Request Body의 주요 내용은 다음과 같습니다:
  • prompt: 자연어로 만들고자 하는 비디오를 설명합니다 (주제, 무엇을 보여줄 것인지, 스타일, 대상).
  • langs: 출력 언어 배열, 예: ["zh-cn", "en"], 기본값은 ["zh-cn"]입니다.
  • aspect: 화면 비율, 9:16 (기본값) / 16:9 / 1:1.
  • duration: 목표 길이(초), 기본값 30.
요청 본체의 모든 필드는 아래 표와 같습니다: 아래는 구체적인 예제를 통해 설명하겠습니다. 예를 들어, 중영 이중 언어, 세로 화면, 20초의 과학 홍보 짧은 비디오를 생성하고자 할 때, 해당 CURL 코드는 다음과 같습니다:
해당 Python 코드는 다음과 같습니다:
실행하면 즉시 결과를 얻을 수 있습니다. 결과는 다음과 같습니다:
반환된 결과의 필드 설명은 다음과 같습니다:
  • success:이번 작업이 성공적으로 제출되었는지 여부.
  • task_id:이번 비디오 생성 작업의 ID, 이후에 이를 사용하여 Maestro 작업 조회 API에서 결과를 폴링합니다.
  • trace_id:이번 요청의 추적 ID, 문제가 발생했을 때 기술 지원에 제공하여 위치를 파악할 수 있습니다.
비디오 제작에 시간이 오래 걸리므로, 인터페이스는 여기서 즉시 task_id를 반환하며, 비디오 렌더링이 완료될 때까지 기다리지 않습니다. 이후 task_id를 사용하여 결과를 폴링해야 하며, 자세한 내용은 “결과 가져오기” 섹션을 참조하십시오.

비디오 유형 및 스타일 지정 (scenario / style)

sceario를 전달하지 않으면 AI가 자동으로 판단합니다(즉, auto와 같습니다); 비디오를 특정 유형으로 고정하고 싶다면 명시적으로 전달하십시오. 예를 들어 세로 화면 단편극을 만들고 싶다면 다음과 같이 지정할 수 있습니다:
  • scenario:비디오 유형, 여기서는 drama(캐릭터 + 대사의 단편극)로 설정합니다.
  • style:시각적 스타일, 여기서는 cinematic(영화 질감)으로 설정합니다.
샘플 CURL 코드 작성 예시는 다음과 같습니다:
일반적인 조합 방식:
  • 내레이션 단편: scenario: "narrated", Lite / Standard / Pro 모두 지원.
  • 자동 자막: scenario: "captions", file_urls를 사용하여 원본 비디오를 전달해야 하며, Lite / Standard / Pro 모두 지원.
  • 디지털 사람 / 음성 내레이션: scenario: "avatar", file_urls를 사용하여 인물 사진을 전달해야 하며, Standard / Pro 지원.
  • 단편극: scenario: "drama"(캐릭터 + 대사), 오직 Pro만 지원.
  • style은 시각적 스타일 프리셋(예: modern / neon / luxury)으로, 유형을 변경하지 않고 관람 경험에만 영향을 미칩니다.
  • voice는 내레이션 음색을 지정하는 데 사용됩니다(예: warm-female / deep-male), 언어와는 무관하며 다국어에서 공통적으로 사용됩니다.
반환 결과는 “기본 사용”과 동일하며, 역시 즉시 task_id를 반환합니다.

다국어 출력

langs에 여러 언어를 전달하면 한 번에 다국어 버전을 생성할 수 있습니다. 첫 번째는 주 언어이며, 이후 각 언어마다 같은 화면을 재사용하고 추가로 더빙 + 렌더링을 하므로, 각 언어마다 +6 포인트만 추가됩니다. 예시:
작업이 완료되면 각 언어는 결과의 하나의 variant에 해당합니다(자세한 내용은 Maestro 작업 조회 API 참조).

기존 비디오에서 반복 작업 (remix / edit / extend)

action과 이전 작업의 ref_task_id를 전달하면 원본 프로젝트를 기반으로 차별적 수정을 할 수 있습니다(예: “2막 제목을 변경”, “다른 더빙으로 변경”, “전체적으로 어둡게”). 작은 수정은 빠르고, 큰 수정은 다시 제작됩니다:
  • remix:원본 비디오 구조에서 다시 해석합니다(주제를 유지하고 표현을 조정).
  • edit:지정된 부분을 세밀하게 수정합니다(예: 제목 변경, 더빙 변경, 색상 조정).
  • extend:원본 비디오를 기반으로 내용을 확장합니다.
반환 결과 역시 즉시 새로운 task_id를 반환하며, 이를 사용하여 폴링하면 반복 작업 후의 최종 결과를 얻을 수 있습니다.

결과 가져오기

비디오 제작에 시간이 오래 걸리므로, 이 인터페이스는 제출 후 즉시 task_id를 반환하며, 이를 사용하여 Maestro 작업 조회 API에서 결과를 폴링해야 합니다:
작업이 완료되면 결과 정보가 반환됩니다(각 언어에 대해 하나의 variant가 있습니다). status는 pending → planning → producing → succeeded(또는 failed)를 거치며, 폴링은 무료이며 포인트를 소모하지 않습니다. 전체 응답 형식 및 이력 목록 조회는 Maestro 작업 조회 API 연동 설명을 참조하십시오.

요금 청구

작업 완료 후 실제 결과물에 따라 요금이 청구되며, 실패한 작업은 요금이 부과되지 않습니다. 요금은 실제 전달된 결과물의 길이와 언어 수에 따라 결정되며, 청구되는 길이는 요청한 길이를 초과하지 않습니다. 특정 언어가 최종적으로 생성되지 않은 경우 해당 언어의 +6 추가 요금도 부과되지 않습니다. 작업 제출 자체는 별도로 요금이 청구되지 않으며, /maestro/tasks 폴링은 무료입니다. 단일 결과물의 포인트는 다음과 같이 계산됩니다:
Maestro는 0.60 포인트/실제 결과물 초로 요금이 청구되며, 5–300초, 최대 4개 언어 및 1080p / 30fps 출력을 지원합니다; 모든 동작 및 장면이 사용 가능합니다. 장면 배율: drama 1.35× / avatar 1.15× / 기타 1×.

오류 처리

API를 호출할 때 오류가 발생하면, API는 해당 오류 코드와 정보를 반환합니다. 예를 들어:
  • 400 invalid_request:잘못된 요청, 아마도 prompt가 누락되었거나 매개변수가 잘못되었습니다.
  • 401 invalid_token:인증되지 않음, 잘못되었거나 누락된 인증 토큰.
  • 403 forbidden:금지됨, 잔액 부족 또는 접근 권한 없음.
  • 429 too_many_requests:요청이 너무 많음, 비율 제한을 초과했습니다.
  • 500 api_error:내부 서버 오류, 서버에서 문제가 발생했습니다.

오류 응답 예시

결론

이 문서를 통해 Maestro 비디오 생성 API를 사용하는 방법을 이해하셨습니다: 자연어 프롬프트 한 문장으로 스크립트, 자료, 음성, 배경 음악, 편집, 자막 및 최종 렌더링을 자동으로 완료할 수 있으며, 비디오 유형, 스타일, 음색, 다국어 출력 및 기존 비디오에 대한 반복 작업을 지정할 수 있습니다. 이 문서가 API를 더 잘 연동하고 사용하는 데 도움이 되기를 바랍니다. 질문이 있으시면 언제든지 기술 지원 팀에 문의해 주십시오.

관련 인터페이스

  • Maestro 작업 조회 API 연동 설명: POST /maestro/videos로 반환된 task_id를 사용하여 작업 상태 및 결과를 조회하거나 과거 작업 목록을 가져옵니다(폴링 무료).