> ## 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 Video Generation API Integration Instructions

> Maestro AI Video Studio API guide - Ace Data Cloud

Maestro é uma interface de produção de vídeo **nativa de Agent**: você usa uma frase em linguagem natural `prompt` para descrever o vídeo desejado (opcionalmente anexando `file_urls` com imagens / vídeos / áudios de referência), e um "diretor de IA" sem cabeça completará automaticamente a seleção de tópicos, escreverá o roteiro, gerará as imagens, a narração, a trilha sonora, a composição e a renderização, resultando em um vídeo final com legendas que será enviado para a CDN.

Este documento irá detalhar as instruções de integração da API de geração de vídeo do Maestro, ajudando você a integrar rapidamente e aproveitar ao máximo as capacidades dessa API.

Esta é uma interface de **tarefa assíncrona**: após a submissão, um `task_id` será retornado imediatamente, e você poderá consultar os resultados através da [API de consulta de tarefas do Maestro](/pt/guides/maestro/maestro_tasks) (`POST /maestro/tasks`) (a consulta é gratuita e não gera custos). Para continuar iterando sobre um vídeo existente, você pode usar `action: remix` / `edit` / `extend` junto com `ref_task_id`.

## Processo de Solicitação

Para usar a API de geração de vídeo do Maestro, primeiro acesse o [Painel de Controle da Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obter seu Token de API, que deve ser guardado para uso futuro.

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

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar; após a conclusão, você será redirecionado de volta para a página atual.

**Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar individualmente para cada serviço.** A primeira solicitação oferece um crédito gratuito, permitindo uma experiência sem custos; quando o crédito estiver baixo, você pode recarregar o saldo geral no [painel de controle](https://platform.acedata.cloud/console/coin).

> 📘 Documentação Completa: [API de Geração de Vídeo do Maestro →](https://platform.acedata.cloud/documents/maestro-videos)

## Uso Básico

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

A forma mais básica de uso requer apenas a passagem de um `prompt` em linguagem natural, e o diretor de IA decidirá automaticamente o roteiro, as imagens, a narração e a edição. Aqui, vamos entender os cabeçalhos de solicitação e o corpo da solicitação que precisam ser configurados.

**Request Headers** incluem:

* `accept`: o formato de resposta desejado, aqui deve ser preenchido como `application/json`, ou seja, formato JSON.
* `authorization`: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação.
* `content-type`: o formato do corpo da solicitação, aqui deve ser preenchido como `application/json`.

**Request Body** inclui principalmente:

* `prompt`: descreve em linguagem natural o vídeo a ser feito (tema, o que mostrar, estilo, público).
* `langs`: array de idiomas de saída, como `["zh-cn", "en"]`, padrão `["zh-cn"]`.
* `aspect`: proporção da imagem, `9:16` (padrão) / `16:9` / `1:1`.
* `duration`: duração alvo (segundos), padrão 30.

Todos os campos do corpo da solicitação estão listados na tabela abaixo:

| Campo | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `prompt` | string | Sim | Descreve em linguagem natural o vídeo a ser feito (tema, o que mostrar, estilo, público). O roteiro, as imagens, a narração e a edição são decididos pela IA. |
| `action` | string | Não | `generate` (padrão, gera um novo vídeo) / `remix` / `edit` / `extend` (itera sobre um vídeo existente, deve ser usado com `ref_task_id`). |
| `ref_task_id` | string | Não | Quando `action` é remix / edit / extend, deve ser preenchido: `task_id` da tarefa histórica que serve como ponto de partida. |
| `file_urls` | string\[] | Não | Mídia de referência (URLs de imagens / vídeos / áudios), por exemplo, imagens de produtos, logotipos ou trechos de material que precisam de legendas. |
| `langs` | string\[] | Não | Idiomas de saída, como `["zh-cn", "en"]`, padrão `["zh-cn"]`. O primeiro é o idioma principal; para cada idioma adicional, reutiliza-se a imagem, adicionando apenas narração + renderização, **cada idioma adicional +6 pontos**. |
| `aspect` | string | Não | `9:16` (padrão) / `16:9` / `1:1`, saída unificada em 1080p/30fps. |
| `duration` | int | Não | Duração alvo (segundos), padrão 30, suporta **5–300 segundos**. A cobrança é feita com base na duração real do vídeo, mas não excederá a duração solicitada. |
| `scenario` | string | Não | Tipo de vídeo: `auto` / `narrated` / `captions` / `avatar` / `drama`. `captions` requer vídeo fonte, `avatar` requer imagem de rosto. |
| `style` | string | Não | Preset de estilo visual: `auto` (padrão) / `cinematic` / `glass` / `luxury` / `swiss` / `modern` / `editorial` / `warm` / `vibrant` / `neon` / `mono` / `pastel` / `bold` / `industrial` / `futuristic` / `retro`, também aceita texto livre como soft prompt. É ortogonal a `scenario`, não altera o roteamento. |
| `voice` | string | Não | Tom da narração (independente do idioma, aplicável a múltiplos idiomas): `auto` (padrão) / `warm-female` / `bright-female` / `anchor-female` / `clean-female` / `calm-male` / `deep-male` / `documentary-male` / `energetic-male` / `storyteller-male`. |

Abaixo, um exemplo específico para demonstrar. Suponha que queremos gerar um vídeo curto de divulgação científica em chinês e inglês, na vertical, com 20 segundos de duração; o código CURL correspondente é o seguinte:

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

O código Python correspondente é o seguinte:

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

Ao clicar em executar, você verá que um resultado será retornado imediatamente, como abaixo:

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

A descrição dos campos do resultado retornado é a seguinte:

* `success`：Se a tarefa foi submetida com sucesso.
* `task_id`：O ID da tarefa de geração de vídeo, que será usado posteriormente para consultar os resultados na [API de consulta de tarefas do Maestro](/pt/guides/maestro/maestro_tasks).
* `trace_id`：O ID de rastreamento da solicitação, que pode ser fornecido ao suporte técnico para localização de problemas.

Como a produção de vídeo leva um tempo considerável, a interface **retorna imediatamente o `task_id`**, sem esperar a conclusão da renderização do vídeo. Em seguida, é necessário usar o `task_id` para consultar os resultados, conforme detalhado na seção "Obter Resultados".

## Especificar Tipo e Estilo de Vídeo (cenário / estilo)

Se `scenario` não for fornecido, a IA fará a determinação automaticamente (equivalente a `auto`); se você quiser fixar o vídeo em um determinado tipo, deve especificar. Por exemplo, para criar um **drama em formato vertical**, você pode especificar o seguinte conteúdo:

* `scenario`：Tipo de vídeo, definido como `drama` (drama curto com personagens + diálogos).
* `style`：Estilo visual, definido como `cinematic` (qualidade cinematográfica).

O código CURL de exemplo é o seguinte:

```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": "Dois colegas de quarto brigam e se reconciliam por causa de um gato, três reviravoltas, final caloroso",
  "scenario": "drama",
  "style": "cinematic",
  "aspect": "9:16",
  "duration": 40
}'
```

Formas comuns de combinação:

* Vídeo narrado: `scenario: "narrated"`, suportado por Lite / Standard / Pro.
* Legendas automáticas: `scenario: "captions"`, deve usar `file_urls` para fornecer o vídeo de origem, suportado por Lite / Standard / Pro.
* Avatar / Narração: `scenario: "avatar"`, deve usar `file_urls` para fornecer uma imagem de retrato, suportado por Standard / Pro.
* Drama: `scenario: "drama"` (personagens + diálogos), suportado apenas por Pro.
* `style` é um preset de estilo visual (como `modern` / `neon` / `luxury`), não altera o tipo, apenas afeta a percepção visual.
* `voice` é usado para especificar o tom da narração (como `warm-female` / `deep-male`), independente do idioma, aplicável a várias línguas.

O resultado retornado é o mesmo que na "Uso Básico", também retornando imediatamente o `task_id`.

## Saída Multilíngue

Ao passar múltiplos idiomas em `langs`, é possível gerar versões multilíngues de uma só vez. O primeiro é o idioma principal, e cada novo idioma **reutiliza o mesmo conjunto de imagens**, apenas adicionando dublagem + renderização, portanto, **cada novo idioma adiciona apenas +6 pontos**. Exemplo:

```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": "Apresentar nosso produto de atendimento ao cliente inteligente, destacando 3 pontos principais",
  "langs": ["zh-cn", "en", "ja"],
  "aspect": "16:9",
  "duration": 30
}'
```

Após a conclusão da tarefa, cada idioma corresponderá a um `variant` nos resultados (veja [API de consulta de tarefas do Maestro](/pt/guides/maestro/maestro_tasks)).

## Iterar em Vídeos Existentes (remix / editar / estender)

Ao passar `action` e o `ref_task_id` da tarefa anterior, é possível fazer modificações diferenciais com base no projeto original (como "mudar o título do ato 2", "trocar a narração", "escurecer o vídeo"). Pequenas alterações são rápidas, grandes alterações podem exigir uma nova produção:

```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": "Mudar o título de abertura para uma frase mais impactante, escurecer um pouco a paleta de cores"
}'
```

* `remix`：Reinterpretar a estrutura do vídeo original (manter o tema, ajustar a apresentação).
* `edit`：Fazer ajustes finos em partes específicas (como mudar título, narração, correção de cores).
* `extend`：Expandir o conteúdo com base no vídeo original.

O resultado retornado também é um novo `task_id`, que deve ser usado para consultar o vídeo iterado.

## Obter Resultados

Como a produção de vídeo leva um tempo considerável, esta interface retorna imediatamente o `task_id` após a submissão, e você deve usá-lo para consultar os resultados na [API de consulta de tarefas do Maestro](/pt/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"
}'
```

Quando a tarefa é concluída, as informações do vídeo final são retornadas (cada idioma corresponde a um `variant`). O `status` passará por `pending → planning → producing → succeeded` (ou `failed`), **a consulta é gratuita e não consome pontos**. O formato completo da resposta e a consulta da lista histórica podem ser consultados na [documentação da API de consulta de tarefas do Maestro](/pt/guides/maestro/maestro_tasks).

## Cobrança

**A cobrança é feita com base no vídeo final entregue, tarefas falhadas não geram cobrança.** A cobrança é baseada na duração real do vídeo entregue e no número de idiomas, e a duração cobrada não excederá a duração solicitada. Se um idioma não for produzido, não será cobrada a taxa adicional de +6. A submissão da tarefa em si não gera cobrança, a consulta `/maestro/tasks` é gratuita.

Os pontos para um vídeo final são calculados pela seguinte fórmula:

```
pontos = duração do vídeo em segundos × 0.60 × multiplicador de cenário + 6 × max(número de idiomas - 1, 0)
```

O Maestro cobra uniformemente **0.60 pontos/segundo de vídeo final**, suportando de 5 a 300 segundos, até 4 idiomas e saída em 1080p / 30fps; todas as ações e cenários são utilizáveis.

Multiplicador de cenário: `drama` 1.35× / `avatar` 1.15× / outros 1×.

| Exemplo | Pontos |
| - | -: |
| Lite 30 segundos | 6 |
| Standard 30 segundos | 18 |
| Standard 60 segundos | 36 |
| Standard 120 segundos | 72 |
| Pro 30 segundos | 36 |
| Pro 300 segundos | 360 |
| Cada novo idioma entregue | +6 |
| Consulta `/maestro/tasks` | Gratuita |

## Tratamento de Erros

Ao chamar a API, se ocorrer um erro, a API retornará o código de erro e a mensagem correspondente. Por exemplo:

* `400 invalid_request`：Solicitação inválida, possivelmente devido a um `prompt` ausente ou parâmetros inválidos.
* `401 invalid_token`：Não autorizado, token de autorização inválido ou ausente.
* `403 forbidden`：Proibido, saldo insuficiente ou acesso negado.
* `429 too_many_requests`：Muitas solicitações, você excedeu o limite de taxa.
* `500 api_error`：Erro interno do servidor, algo deu errado no servidor.

### Exemplo de Resposta de Erro

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

## Conclusão

Através deste documento, você já entendeu como usar a API de geração de vídeo do Maestro: com apenas um `prompt` em linguagem natural, é possível completar automaticamente o roteiro, materiais, narração, trilha sonora, edição, legendas e renderização do vídeo final, além de suportar a especificação do tipo de vídeo, estilo, tom, saída multilíngue e iteração sobre vídeos existentes. Esperamos que este documento possa ajudá-lo a integrar e usar melhor essa API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico.

## Interfaces Relacionadas

* [Instruções de integração da API de consulta de tarefas do Maestro](/pt/guides/maestro/maestro_tasks): use `POST /maestro/videos` para consultar o status e os resultados da tarefa com o `task_id` retornado, ou para puxar a lista de tarefas históricas (polling gratuito).


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