> ## 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는 **Agent 원주율** 비디오 제작 인터페이스입니다: 자연어 `prompt`로 원하는 비디오를 설명하면 (선택적으로 `file_urls`로 참조 이미지 / 비디오 / 오디오를 첨부할 수 있습니다), 무헤드의 "AI 감독"이 자동으로 주제를 정하고, 스크립트를 작성하고, 화면을 생성하고, 더빙하고, 배경 음악을 추가하고, 합성 및 렌더링을 수행하여 최종적으로 자막이 포함된 완성된 영상을 생성하고 CDN에 업로드합니다.

본 문서에서는 Maestro 비디오 생성 API의 연동 설명을 자세히 소개하여, 귀하가 신속하게 통합하고 API의 기능을 충분히 활용할 수 있도록 돕겠습니다.

이것은 **비동기 작업** 인터페이스입니다: 제출 후 즉시 `task_id`가 반환되며, 이후 [Maestro 작업 조회 API](/ko/guides/maestro/maestro_tasks) (`POST /maestro/tasks`)를 통해 결과를 폴링하여 가져옵니다 (폴링은 무료로 청구되지 않음). 기존 비디오에서 계속 반복 작업을 하려면 `action: remix` / `edit` / `extend`와 함께 `ref_task_id`를 사용할 수 있습니다.

## 신청 절차

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-videos)

## 기본 사용법

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

요청 본체의 모든 필드는 아래 표와 같습니다:

| 필드 | 유형 | 필수 | 설명 |
| - | - | - | - |
| `prompt` | string | 예 | 자연어로 만들고자 하는 비디오를 설명합니다 (주제, 무엇을 보여줄 것인지, 스타일, 대상). 스크립트, 화면, 더빙, 편집은 AI가 결정합니다. |
| `action` | string | 아니오 | `generate` (기본값, 새 비디오 생성) / `remix` / `edit` / `extend` (기존 비디오에서 반복 작업, `ref_task_id`와 함께 사용해야 함) |
| `ref_task_id` | string | 아니오 | `action`이 remix / edit / extend일 때 필수: 시작점으로 사용할 과거 작업 `task_id` |
| `file_urls` | string\[] | 아니오 | 참조 미디어 (이미지 / 비디오 / 오디오 URL), 예: 출연할 제품 이미지, 로고, 또는 자막을 추가할 소스 클립 |
| `langs` | string\[] | 아니오 | 출력 언어, 예: `["zh-cn", "en"]`, 기본값은 `["zh-cn"]`입니다. 첫 번째는 주 언어입니다; 언어가 추가될 때마다 화면을 재사용하고, 더빙 + 렌더링만 추가됩니다, **언어가 추가될 때마다 +6 포인트** |
| `aspect` | string | 아니오 | `9:16` (기본값) / `16:9` / `1:1`, 통일된 출력 1080p/30fps |
| `duration` | int | 아니오 | 목표 길이(초), 기본값 30, **5–300 초** 지원. 실제 완성된 비디오 길이에 따라 요금이 청구되지만 요청한 길이를 초과하지 않습니다. |
| `scenario` | string | 아니오 | 비디오 유형: `auto` / `narrated` / `captions` / `avatar` / `drama`. `captions`는 원본 비디오를 제공해야 하며, `avatar`는 인물 사진을 제공해야 합니다. |
| `style` | string | 아니오 | 시각적 스타일 프리셋: `auto` (기본값) / `cinematic` / `glass` / `luxury` / `swiss` / `modern` / `editorial` / `warm` / `vibrant` / `neon` / `mono` / `pastel` / `bold` / `industrial` / `futuristic` / `retro`, 자유 텍스트를 소프트 프롬프트로 수용합니다. `scenario`와는 교차하지 않으며 라우팅을 변경하지 않습니다. |
| `voice` | string | 아니오 | 내레이션 음색 (언어와 무관하게, 다국어 공통): `auto` (기본값) / `warm-female` / `bright-female` / `anchor-female` / `clean-female` / `calm-male` / `deep-male` / `documentary-male` / `energetic-male` / `storyteller-male` |

아래는 구체적인 예제를 통해 설명하겠습니다. 예를 들어, 중영 이중 언어, 세로 화면, 20초의 과학 홍보 짧은 비디오를 생성하고자 할 때, 해당 CURL 코드는 다음과 같습니다:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "20초 안에 벡터 데이터베이스가 무엇인지 설명하고, 기초가 없는 관객에게 적합하며, 마지막에 기억할 포인트를 주십시오.",
  "langs": ["zh-cn", "en"],
  "aspect": "9:16",
  "duration": 20
}'
```

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

```python theme={null}
import requests

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

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

payload = {
    "prompt": "20초 안에 벡터 데이터베이스가 무엇인지 설명하고, 기초가 없는 관객에게 적합하며, 마지막에 기억할 포인트를 주십시오.",
    "langs": ["zh-cn", "en"],
    "aspect": "9:16",
    "duration": 20
}

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

실행하면 즉시 결과를 얻을 수 있습니다. 결과는 다음과 같습니다:

```json theme={null}
{
  "success": true,
  "task_id": "f57e99c4f60f4373a15517742ce2357d",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b"
}
```

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

* `success`：이번 작업이 성공적으로 제출되었는지 여부.
* `task_id`：이번 비디오 생성 작업의 ID, 이후에 이를 사용하여 [Maestro 작업 조회 API](/ko/guides/maestro/maestro_tasks)에서 결과를 폴링합니다.
* `trace_id`：이번 요청의 추적 ID, 문제가 발생했을 때 기술 지원에 제공하여 위치를 파악할 수 있습니다.

비디오 제작에 시간이 오래 걸리므로, 인터페이스는 여기서 **즉시 `task_id`를 반환**하며, 비디오 렌더링이 완료될 때까지 기다리지 않습니다. 이후 `task_id`를 사용하여 결과를 폴링해야 하며, 자세한 내용은 "결과 가져오기" 섹션을 참조하십시오.

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

`sceario`를 전달하지 않으면 AI가 자동으로 판단합니다(즉, `auto`와 같습니다); 비디오를 특정 유형으로 고정하고 싶다면 명시적으로 전달하십시오. 예를 들어 **세로 화면 단편극**을 만들고 싶다면 다음과 같이 지정할 수 있습니다:

* `scenario`：비디오 유형, 여기서는 `drama`(캐릭터 + 대사의 단편극)로 설정합니다.
* `style`：시각적 스타일, 여기서는 `cinematic`(영화 질감)으로 설정합니다.

샘플 CURL 코드 작성 예시는 다음과 같습니다:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "두 명의 룸메이트가 고양이 때문에 다투었다가 화해하는 이야기, 세 번의 반전, 따뜻한 결말",
  "scenario": "drama",
  "style": "cinematic",
  "aspect": "9:16",
  "duration": 40
}'
```

일반적인 조합 방식:

* 내레이션 단편: `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 포인트**만 추가됩니다. 예시:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "우리의 스마트 고객 서비스 제품을 소개하며 3가지 핵심 판매 포인트를 강조합니다.",
  "langs": ["zh-cn", "en", "ja"],
  "aspect": "16:9",
  "duration": 30
}'
```

작업이 완료되면 각 언어는 결과의 하나의 `variant`에 해당합니다(자세한 내용은 [Maestro 작업 조회 API](/ko/guides/maestro/maestro_tasks) 참조).

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

`action`과 이전 작업의 `ref_task_id`를 전달하면 원본 프로젝트를 기반으로 차별적 수정을 할 수 있습니다(예: "2막 제목을 변경", "다른 더빙으로 변경", "전체적으로 어둡게"). 작은 수정은 빠르고, 큰 수정은 다시 제작됩니다:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "remix",
  "ref_task_id": "f57e99c4f60f4373a15517742ce2357d",
  "prompt": "시작 제목을 더 임팩트 있는 문구로 바꾸고, 전체 색상을 좀 더 어둡게 조정합니다."
}'
```

* `remix`：원본 비디오 구조에서 다시 해석합니다(주제를 유지하고 표현을 조정).
* `edit`：지정된 부분을 세밀하게 수정합니다(예: 제목 변경, 더빙 변경, 색상 조정).
* `extend`：원본 비디오를 기반으로 내용을 확장합니다.

반환 결과 역시 즉시 새로운 `task_id`를 반환하며, 이를 사용하여 폴링하면 반복 작업 후의 최종 결과를 얻을 수 있습니다.

## 결과 가져오기

비디오 제작에 시간이 오래 걸리므로, 이 인터페이스는 제출 후 즉시 `task_id`를 반환하며, 이를 사용하여 [Maestro 작업 조회 API](/ko/guides/maestro/maestro_tasks)에서 결과를 폴링해야 합니다:

```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"
}'
```

작업이 완료되면 결과 정보가 반환됩니다(각 언어에 대해 하나의 `variant`가 있습니다). `status`는 `pending → planning → producing → succeeded`(또는 `failed`)를 거치며, **폴링은 무료이며 포인트를 소모하지 않습니다**. 전체 응답 형식 및 이력 목록 조회는 [Maestro 작업 조회 API 연동 설명](/ko/guides/maestro/maestro_tasks)을 참조하십시오.

## 요금 청구

**작업 완료 후 실제 결과물에 따라 요금이 청구되며, 실패한 작업은 요금이 부과되지 않습니다.** 요금은 실제 전달된 결과물의 길이와 언어 수에 따라 결정되며, 청구되는 길이는 요청한 길이를 초과하지 않습니다. 특정 언어가 최종적으로 생성되지 않은 경우 해당 언어의 +6 추가 요금도 부과되지 않습니다. 작업 제출 자체는 별도로 요금이 청구되지 않으며, `/maestro/tasks` 폴링은 무료입니다.

단일 결과물의 포인트는 다음과 같이 계산됩니다:

```
포인트 = 결과물 길이 초 × 0.60 × 장면 배율 + 6 × max(언어 수 - 1, 0)
```

Maestro는 **0.60 포인트/실제 결과물 초**로 요금이 청구되며, 5–300초, 최대 4개 언어 및 1080p / 30fps 출력을 지원합니다; 모든 동작 및 장면이 사용 가능합니다.

장면 배율: `drama` 1.35× / `avatar` 1.15× / 기타 1×.

| 예시 | 포인트 |
| - | -: |
| Lite 30초 | 6 |
| Standard 30초 | 18 |
| Standard 60초 | 36 |
| Standard 120초 | 72 |
| Pro 30초 | 36 |
| Pro 300초 | 360 |
| 각 추가 실제 전달 언어 | +6 |
| `/maestro/tasks` 폴링 | 무료 |

## 오류 처리

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

* `400 invalid_request`：잘못된 요청, 아마도 `prompt`가 누락되었거나 매개변수가 잘못되었습니다.
* `401 invalid_token`：인증되지 않음, 잘못되었거나 누락된 인증 토큰.
* `403 forbidden`：금지됨, 잔액 부족 또는 접근 권한 없음.
* `429 too_many_requests`：요청이 너무 많음, 비율 제한을 초과했습니다.
* `500 api_error`：내부 서버 오류, 서버에서 문제가 발생했습니다.

### 오류 응답 예시

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "가져오기 실패"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## 결론

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

## 관련 인터페이스

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


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