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 comapplication/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 comapplication/json.
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.
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:
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.
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)
Quandoscenario 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 comodrama(drama curto com personagens + diálogos).style: estilo visual, definido aqui comocinematic(qualidade cinematográfica).
- Vídeo curto narrado:
scenario: "narrated". - Legendas automáticas:
scenario: "captions", é necessário usarfile_urlspara enviar o vídeo de origem. - Avatar digital / fala para a câmera:
scenario: "avatar", é necessário usarfile_urlspara enviar uma imagem de retrato. - Drama curto:
scenario: "drama"(personagens + diálogos). styleé uma predefinição de estilo visual (comomodern/neon/luxury), não altera o tipo, apenas afeta a aparência.voiceé usado para especificar o timbre da narração (comowarm-female/deep-male), não está relacionado ao idioma e é aplicável entre idiomas.
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)
Envieaction 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.
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 otask_id após o envio, e você precisa usá-lo para consultar os resultados na API de consulta de tarefas do Maestro:
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.
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 depromptou 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 umprompt 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
- Instruções de integração da API de consulta de tarefas do Maestro: use o
task_idretornado porPOST /maestro/videospara consultar o status e o resultado da tarefa, ou obter a lista de tarefas históricas (consulta gratuita).

