Saltar para o conteúdo principal
Maestro é uma interface de produção de vídeo nativa para Agent: você usa um prompt em linguagem natural para descrever o vídeo desejado (opcionalmente anexando imagens / vídeos / áudios de referência com file_urls), e um «diretor de IA» sem interface gráfica concluirá automaticamente a seleção do tema, a escrita do roteiro, a geração de imagens, a narração, a trilha sonora, a composição e a renderização, produzindo por fim um vídeo final com legendas e fazendo upload para a CDN. Este documento apresentará detalhadamente as instruções de integração da API de geração de vídeo Maestro, ajudando você a integrar rapidamente e aproveitar ao máximo os recursos desta API. Esta é uma interface de tarefa assíncrona: após o envio, task_id será retornado imediatamente e, em seguida, o resultado será obtido por polling por meio da API de consulta de tarefas Maestro (POST /maestro/tasks) (o polling é gratuito e não é cobrado). Para continuar iterando sobre um vídeo existente, você pode usar action: remix / edit / extend em conjunto com ref_task_id.

Processo de solicitação

Para usar a API de geração de vídeo Maestro, primeiro acesse o Console Ace Data Cloud para obter seu API Token e guarde-o para uso posterior. Se você ainda não estiver conectado ou registrado, será automaticamente redirecionado para a página de login, onde será convidado a se registrar e entrar; após a conclusão, retornará automaticamente à página atual. Um único API Token pode chamar todos os serviços da plataforma, sem necessidade de solicitar um separadamente para cada serviço. A primeira solicitação concede créditos gratuitos para experimentar sem custo; quando os créditos forem insuficientes, você pode recarregar o saldo geral no console.
📘 Documentação completa: API de geração de vídeo Maestro →

Uso básico

POST https://api.acedata.cloud/maestro/videos O uso mais básico requer apenas o envio de uma descrição em linguagem natural em prompt. O diretor de IA decidirá automaticamente o roteiro, as imagens, a narração e a edição. Primeiro, vamos entender os cabeçalhos e o corpo da solicitação que precisam ser configurados. Request Headers incluem:
  • accept: o formato em que você deseja receber a resposta. Preencha com application/json, ou seja, o formato JSON.
  • authorization: a chave para chamar a API. Após solicitá-la, você poderá selecioná-la diretamente na lista suspensa.
  • content-type: o formato do corpo da solicitação. Preencha com application/json.
Request Body inclui principalmente:
  • prompt: descreva em linguagem natural o vídeo que deseja criar (tema, o que será exibido, estilo e público-alvo).
  • langs: matriz de idiomas do vídeo final. Envie apenas um idioma por vez, como ["zh-cn"]. O padrão é ["zh-cn"].
  • aspect: proporção da imagem, 9:16 (padrão) / 16:9 / 1:1.
  • duration: duração desejada (segundos). O padrão é 30.
Todos os campos do corpo da solicitação são mostrados na tabela abaixo: A seguir, demonstraremos com um exemplo específico. Suponha que desejamos gerar um vídeo curto educativo em chinês, no formato vertical, com 20 segundos. O código CURL correspondente é o seguinte:
O código Python correspondente é o seguinte:
Clique em Executar e você verá que um resultado será retornado imediatamente, conforme mostrado abaixo:
Os campos do resultado retornado são descritos a seguir:
  • success: indica se esta tarefa foi enviada com sucesso.
  • task_id: o ID desta tarefa de geração de vídeo. Use-o posteriormente para consultar os resultados pela API de consulta de tarefas do Maestro.
  • trace_id: o ID de rastreamento desta solicitação. Em caso de problemas, forneça-o ao suporte técnico para investigação.
Devido ao longo tempo de produção do vídeo, a API retorna task_id imediatamente e não aguarda a conclusão da renderização do vídeo. Em seguida, use task_id para consultar o resultado, conforme detalhado na seção «Obter resultado».

Especificar tipo e estilo de vídeo (scenario / style)

Quando scenario não é enviado, ele é determinado automaticamente pela IA (equivalente a auto); se quiser fixar o vídeo em determinado tipo, envie-o explicitamente. Por exemplo, para criar um drama curto vertical, é possível especificar o seguinte:
  • scenario: tipo de vídeo, definido aqui como drama (drama curto com personagens + diálogos).
  • style: estilo visual, definido aqui como cinematic (qualidade cinematográfica).
O código CURL de exemplo de preenchimento é o seguinte:
Formas comuns de combinação:
  • Vídeo curto narrado: scenario: "narrated".
  • Legendas automáticas: scenario: "captions", é necessário usar file_urls para enviar o vídeo de origem.
  • Avatar digital / fala para a câmera: scenario: "avatar", é necessário usar file_urls para enviar uma imagem de retrato.
  • Drama curto: scenario: "drama" (personagens + diálogos).
  • style é uma predefinição de estilo visual (como modern / neon / luxury), não altera o tipo, apenas afeta a aparência.
  • voice é usado para especificar o timbre da narração (como warm-female / deep-male), não está relacionado ao idioma e é aplicável entre idiomas.
O resultado retornado é igual ao de “Uso básico”, retornando também o task_id imediatamente.

Idioma do vídeo final

Uma tarefa entrega apenas um vídeo final em um único idioma. langs só pode conter um código de idioma, como ["zh-cn"] ou ["en"]; o envio de vários idiomas retornará 400. Se precisar de vídeos em idiomas diferentes, crie tarefas separadamente. A seleção de idioma não altera o preço por segundo.

Iterar sobre um vídeo existente (remix / edit / extend)

Envie action e o ref_task_id da tarefa anterior para fazer modificações incrementais com base no projeto original (como “alterar o título da cena 2”, “trocar a narração”, “escurecer o conjunto”). Pequenas alterações são rápidas; grandes alterações refarão o vídeo:
  • remix: reinterpretar com base na estrutura do vídeo original (mantém o tema, ajusta a apresentação).
  • edit: realizar refinamentos em partes específicas (como trocar o título, trocar a narração, fazer correção de cor).
  • extend: estender o conteúdo com base no vídeo original.
O resultado retornado também retorna imediatamente um novo task_id; use-o para consultar e obter o vídeo final após a iteração.

Obter resultados

Como a produção de vídeos leva bastante tempo, esta interface retorna imediatamente o task_id após o envio, e você precisa usá-lo para consultar os resultados na API de consulta de tarefas do Maestro:
Quando a tarefa for concluída, uma informação de vídeo final será retornada (localizada no array variants). O status passará por pending → planning → producing → succeeded (ou failed), e a consulta é gratuita e não consome créditos. Para o formato completo da resposta e a consulta de listas históricas, consulte as instruções de integração da API de consulta de tarefas do Maestro.

Cobrança

Após o sucesso da tarefa, a cobrança é feita com base na duração real do vídeo final entregue; falhas não são cobradas. A duração faturável é calculada em segundos inteiros e não excede a duração solicitada; quando não for possível ler a duração do vídeo final, será usada como alternativa a duração solicitada. O envio da tarefa em si não é cobrado separadamente, e a consulta de /maestro/tasks é gratuita.
Todos os cenários, ações e idiomas usam o mesmo preço, sem multiplicadores por cenário ou cobranças adicionais por idioma. Cada tarefa entrega apenas um vídeo final em um único idioma. A duração-alvo solicitada suporta 5–300 segundos, com saída uniforme em 1080p / 30fps.

Tratamento de erros

Ao chamar a API, se ocorrer um erro, a API retornará o código e a mensagem de erro correspondentes. Por exemplo:
  • 400 invalid_request: Solicitação inválida, possivelmente devido à ausência de prompt ou a parâmetros inválidos.
  • 401 invalid_token: Não autorizado, token de autorização inválido ou ausente.
  • 403 forbidden: Proibido, saldo ou acesso insuficiente.
  • 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

Conclusão

Por meio deste documento, você já entendeu como usar a API de geração de vídeos Maestro: basta um prompt em linguagem natural para concluir automaticamente o roteiro, os materiais, a narração, a trilha sonora, a edição, as legendas e a renderização do vídeo final, além de oferecer suporte à especificação do tipo de vídeo, estilo, timbre, idioma do vídeo final e iteração sobre vídeos existentes. Esperamos que este documento possa ajudá-lo a integrar e usar melhor esta API. Se tiver qualquer dúvida, entre em contato com nossa equipe de suporte técnico a qualquer momento.

Interfaces relacionadas