> ## 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. # Development Dreamina Tasks > Dreamina API guide - Ace Data Cloud ## Integração e Uso da API Dreamina Tasks A API Dreamina Tasks é usada para consultar os resultados da execução de tarefas de vídeo de humanos digitais criadas pela [API de Geração de Vídeo Dreamina](https://platform.acedata.cloud/documents/dreamina-videos-integration). Quando você passa `callback_url` ou `async: true` na interface de geração, a interface retorna imediatamente um `task_id`, que você pode usar para consultar o status da tarefa e o endereço do vídeo final através desta interface, usando `task_id` ou `trace_id`. **Esta interface é gratuita.** ## Processo de Solicitação Para usar a série de APIs Dreamina, 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. 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 para que você possa experimentar; quando o crédito estiver baixo, você pode recarregar o saldo geral no [painel de controle](https://platform.acedata.cloud/console/coin). ## Parâmetros de Solicitação **Cabeçalhos da Solicitação** * `accept`: especifica que a resposta deve ser no formato JSON, preenchendo `application/json`. * `authorization`: chave para chamar a API, no formato `Bearer {token}`. * `content-type`: preencha com `application/json`. **Corpo da Solicitação** | Parâmetro | Tipo | Obrigatório | Descrição | | - | - | - | - | | `action` | string | Não | Tipo de operação, `retrieve` (padrão, consulta única) ou `retrieve_batch` (consulta em lote) | | `id` | string | Não | ID da tarefa a ser consultada (o `task_id` retornado ao criar o vídeo) | | `trace_id` | string | Não | ID de rastreamento da tarefa a ser consultada, pode ser usado em vez de `id` | | `ids` | string\[] | Não | Lista de IDs de tarefas para consulta em lote, usada com `retrieve_batch` | > Ao consultar uma única tarefa, pelo menos um de `id` ou `trace_id` deve ser fornecido. ## Consulta de uma Única Tarefa ### CURL ```bash theme={null} curl -X POST 'https://api.acedata.cloud/dreamina/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "retrieve", "id": "362b4fed-67bd-11f1-ad11-00163e57d510" }' ``` ### Python ```python theme={null} import requests url = "https://api.acedata.cloud/dreamina/tasks" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "action": "retrieve", "id": "362b4fed-67bd-11f1-ad11-00163e57d510" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ### Exemplo de Resposta Após uma solicitação bem-sucedida, a API retorna os detalhes da tarefa. `request` é o corpo da solicitação ao criar a tarefa, `response` é o corpo da resposta após a conclusão da tarefa, onde `data.video_url` é o endereço do vídeo do humano digital gerado: ```json theme={null} { "id": "362b4fed-67bd-11f1-ad11-00163e57d510", "started_at": 1769262721.823, "finished_at": 1769262769.123, "elapsed": 47.3, "trace_id": "a9063166-26ed-4451-85b5-54e896817c69", "request": { "model": "omnihuman-1.5", "image_url": "https://cdn.acedata.cloud/4hfydw.jpg", "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav" }, "response": { "success": true, "data": { "task_id": "362b4fed67bd11f1ad1100163e57d510", "status": "done", "video_url": "https://cdn.acedata.cloud/634d760216.mp4", "image_url": "https://cdn.acedata.cloud/4hfydw.jpg", "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav" } } } ``` Descrição dos Campos: * `id`: ID único da tarefa de geração de vídeo. * `trace_id`: ID de rastreamento da solicitação, usado para resolução de problemas. * `request`: Conteúdo da solicitação enviado ao criar a tarefa. * `response`: Conteúdo da resposta retornado após a conclusão da tarefa. Quando `response.data.status` é `done`, `response.data.video_url` é o endereço final do vídeo. * `created_at`: Hora de criação da tarefa, timestamp Unix (segundos, ponto flutuante). * `started_at`: Hora de início da execução da tarefa, timestamp Unix (segundos, ponto flutuante). * `finished_at`: Hora de conclusão da tarefa, timestamp Unix (segundos, ponto flutuante). Este campo não é retornado se a tarefa não estiver concluída. * `elapsed`: Tempo gasto na execução da tarefa, em segundos (ponto flutuante, com 3 casas decimais). Este campo não é retornado se a tarefa não estiver concluída. > Se a tarefa ainda não estiver concluída, o `status` pode não ser `done`; se a tarefa não existir ou ainda não tiver gerado resultados, a interface retornará um objeto vazio `{}`, por favor, tente novamente mais tarde. ## Consulta em Lote de Tarefas Defina `action` como `retrieve_batch` e passe um array `ids`: ```bash theme={null} curl -X POST 'https://api.acedata.cloud/dreamina/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "retrieve_batch", "ids": [ "362b4fed-67bd-11f1-ad11-00163e57d510", "0c0b4d3a-2f1e-4a6b-9c2d-2b3c4d5e6f70" ] }' ``` No resultado retornado, `items` é um array de detalhes das tarefas em lote (cada elemento tem o mesmo formato que o resultado de uma consulta única), e `count` é o número de tarefas retornadas nesta solicitação. ## Tratamento de Erros Ao chamar a API, se ocorrer um erro, será retornado o código e a mensagem de erro correspondentes: * `400 bad_request`: Erro na solicitação, pode faltar `id` / `trace_id` ou outros parâmetros necessários. * `401 invalid_token`: Não autorizado, o token de autorização é inválido ou está ausente. * `429 too_many_requests`: Muitas solicitações, excedeu o limite de taxa. * `500 api_error`: Erro interno do servidor. ### Exemplo de Resposta de Erro ```json theme={null} { "error": { "code": "bad_request", "message": "id or trace_id is required to retrieve a task" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusão Com este documento, você aprendeu como usar a API Dreamina Tasks para consultar os resultados de tarefas de vídeo de humanos digitais, tanto individuais quanto em lote. Combinando com a interface de geração no modo assíncrono `callback_url` / `async`, você pode implementar uma consulta estável. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.