POST /maestro/videos).
Este documento apresentará em detalhes a documentação de integração da API de consulta de tarefas Maestro. Como a geração de vídeos é uma tarefa assíncrona, após o envio é necessário usar esta interface para consultar o progresso e o vídeo final por polling, o polling é gratuito e não consome créditos.
POST https://api.acedata.cloud/maestro/tasks
Processo de solicitação
Para usar a API de consulta de tarefas Maestro, primeiro acesse o Console do Ace Data Cloud para obter seu API Token e guarde-o para uso posterior.
Se você ainda não estiver conectado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e fazer login; 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 uma cota gratuita para experimentação; quando a cota for insuficiente, é possível recarregar o saldo geral no console.
📘 Documentação completa: API de consulta de tarefas Maestro →
Consultar uma única tarefa
Sobre como criar uma tarefa de vídeo, consulte a documentação da API de geração de vídeos Maestro. Usaremos como exemplo um ID de tarefa retornado por ela:f57e99c4f60f4373a15517742ce2357d, para demonstrar como consultar seu status e resultado.
Configurar os cabeçalhos e o corpo da solicitação
Os Request Headers incluem:accept: especifica o resultado da resposta a ser recebido no formato JSON, preenchido aqui comoapplication/json.authorization: a chave para chamar a API, que pode ser selecionada diretamente na lista suspensa após a solicitação.content-type: o formato do corpo da solicitação, preenchido aqui comoapplication/json.
Exemplo de código
O código CURL correspondente é o seguinte:Exemplo de resposta
Após a solicitação ser bem-sucedida, a API retornará o status e o resultado desta tarefa de vídeo. Um exemplo de retorno quando a tarefa for concluída é o seguinte (o arrayvariants contém um vídeo final):
id: o ID desta tarefa de vídeo, usado para identificar exclusivamente esta tarefa de geração de vídeo.status: status da tarefa, com valorpending → planning → producing → succeeded(oufailed). A conclusão da tarefa deve ser determinada por estestatusde nível superior.elapsed: tempo decorrido da tarefa (segundos).progress: objeto de progresso de nível superior.percent(0–100) será 100 após a conclusão bem-sucedida da tarefa;stageemessagerefletem o evento de progresso mais recente do diretor de IA (portanto, após a conclusão,stageainda poderá ser a última etapa de execução, comoproducing) e podem ser usados diretamente para exibir uma barra de progresso.request: corpo da solicitação ao iniciar a tarefa.response: informações retornadas pela tarefa.success: indica se a tarefa foi bem-sucedida.data.variants: contém um objeto de vídeo final no idioma selecionado, incluindolang,aspect,title,output_url(URL para download do vídeo final) etc.data.project: artefatos de todo o projeto, incluindotarball_url(pacote do projeto) eoutputs(link do vídeo final).data.progress: array de eventos de progresso adicionados por etapa (log somente de anexação), que pode ser usado para exibir o progresso detalhado em tempo real.
created_at: horário de criação da tarefa, carimbo de data/hora Unix (segundos).started_at: horário de início da execução da tarefa, carimbo de data/hora Unix (segundos). Será null se a tarefa ainda não tiver começado.finished_at: hora de conclusão da tarefa, carimbo de data/hora Unix (segundos). É null quando a tarefa não foi concluída.
Consultar lista de histórico
Basta passaraction: retrieve_batch para obter as tarefas recentes do executor atualmente conectado (em ordem decrescente de hora de criação), podendo ser usado na página de lista «Meus vídeos». A lista de histórico é isolada por identidade de login.
O Request Body inclui:
Exemplo de código
O código CURL correspondente é o seguinte:Exemplo de resposta
Após a solicitação ser bem-sucedida, a API retornará a lista de tarefas históricas do usuário atual:count: O número total de tarefas visíveis para o executor atualmente autenticado, não afetado pelas condições de tempo ou porlimit.items: O array de tarefas filtradas pelas condições de tempo e porlimit, ordenado por tempo de criação em ordem decrescente; o formato de cada elemento é consistente com o resultado retornado de «consultar uma única tarefa».
Recomendações de polling
Como a produção de vídeo leva mais tempo, ostatus passará por pending → planning → producing → succeeded (ou failed). Recomenda-se realizar polling a cada 5–10 segundos, até que o status se torne succeeded ou failed. Você pode usar progress.percent de nível superior para exibir uma barra de progresso em tempo real. O polling desta interface é gratuito e não consome créditos.
Tratamento de erros
Ao chamar a API, caso ocorra um erro, a API retornará o código e a mensagem de erro correspondentes. Por exemplo:401 invalid_token: Não autorizado, token de autorização inválido ou ausente.404 not_found: Tarefa não encontrada, o task_id fornecido não existe.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 consulta de tarefas do Maestro para consultar o status e os resultados de uma única tarefa, bem como obter a lista de tarefas históricas do usuário atual. Esperamos que este documento possa ajudá-lo a integrar e usar melhor esta API. Se tiver alguma 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 geração de vídeo Maestro: Produza automaticamente um vídeo finalizado com legendas usando uma frase de prompt em linguagem natural; após o envio,
task_idserá retornado e, em seguida, use esta interface para consultar os resultados por polling.

