> ## 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.

# Guia de Integração da API de Consulta de Tarefas MiniMax H3

> Minimax API guide - Ace Data Cloud

Este artigo apresenta a integração e o uso da API de consulta de tarefas MiniMax H3. Esta interface é usada para consultar, listar em lote ou excluir tarefas assíncronas criadas pela [API de geração de vídeo MiniMax H3](https://platform.acedata.cloud/documents/minimax-videos-integration).

## Processo de solicitação

Para usar a API de consulta de tarefas MiniMax H3, primeiro acesse o [Console do Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obter seu API Token e guarde-o para uso posterior.

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

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 fazer login. Após a conclusão, você retornará automaticamente à página atual.

**Um único API Token pode chamar todos os serviços da plataforma, não sendo necessário solicitar um separadamente para cada serviço.** A primeira solicitação concede uma cota gratuita para experimentação sem custo; quando a cota for insuficiente, você poderá recarregar o saldo universal no [console](https://platform.acedata.cloud/console/coin).

> 📘 Documentação completa: [API de Consulta de Tarefas MiniMax H3 →](https://platform.acedata.cloud/documents/minimax-tasks-integration)

Ao consultar uma tarefa, deve-se usar o mesmo Token que criou essa tarefa. Recomenda-se salvar o Token como uma variável de ambiente e não escrevê-lo no código-fonte nem enviá-lo ao repositório de versões:

```bash theme={null}
export ACEDATACLOUD_API_KEY="YOUR_API_KEY"
```

## Visão geral da interface

* **Base URL**：`https://api.acedata.cloud`
* **Endpoint**：`POST /minimax/tasks`
* **Método de autenticação**：incluir `authorization: Bearer {token}` no HTTP Header
* **Cabeçalhos de solicitação**：
  * `accept: application/json`
  * `content-type: application/json`
* **Consultar uma única tarefa**：`action=retrieve`, informar `id`
* **Consultar tarefas em lote**：`action=retrieve_batch`, permite filtrar por ID da tarefa, intervalo de tempo e condições de paginação
* **Excluir tarefa**：`action=delete`, informar `id`
* **Informações de cobrança**：a consulta de tarefas é gratuita e não gera cobrança duplicada

Após criar um vídeo, é necessário salvar o `task_id`. Recomenda-se consultar aproximadamente a cada 10 segundos, até que a tarefa entre em um estado terminal.

## Parâmetros da solicitação

| Parâmetro | Tipo | Obrigatório | Ações aplicáveis | Descrição |
| - | - | - | - | - |
| `action` | string | Não | Todas | `retrieve`, `retrieve_batch` ou `delete`; o padrão é `retrieve` |
| `id` | string | Obrigatório condicionalmente | `retrieve`, `delete` | ID de uma única tarefa |
| `ids` | string\[] | Não | `retrieve_batch` | Retorna apenas os IDs de tarefa especificados; quando omitido, lista as tarefas segundo outras condições |
| `limit` | integer | Não | `retrieve_batch` | Número máximo de tarefas retornadas nesta solicitação |
| `offset` | integer | Não | `retrieve_batch` | Número de tarefas a ignorar na lista de resultados, usado para paginação |
| `created_at_min` | number | Não | `retrieve_batch` | Limite inferior do horário de criação, timestamp Unix em segundos |
| `created_at_max` | number | Não | `retrieve_batch` | Limite superior do horário de criação, timestamp Unix em segundos |

Os usos das três ações são os seguintes:

| `action` | Uso | Parâmetros necessários | Estrutura da resposta |
| - | - | - | - |
| `retrieve` | Consulta o status e o resultado de uma tarefa | `id` | `{ "task": {...} }` |
| `retrieve_batch` | Consulta tarefas em lote por ID da tarefa, horário e condições de paginação | `ids`, intervalo de tempo, `offset`, `limit` opcionais | `{ "items": [...], "total": number }` |
| `delete` | Cancela ou exclui o registro da tarefa conforme seu status atual | `id` | `{ "id": "...", "deleted": true }` |

## Consultar uma única tarefa

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/minimax/tasks' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "retrieve",
    "id": "f5977217-ed2c-40da-adbe-93d08235618f"
  }'
```

Abaixo está a resposta de uma tarefa real bem-sucedida:

```json theme={null}
{
  "task": {
    "id": "f5977217-ed2c-40da-adbe-93d08235618f",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1786184658,
    "updated_at": 1786184758,
    "content": {
      "url": "https://cdn.acedata.cloud/assets/examples/minimax/f5977217-ed2c-40da-adbe-93d08235618f-b080c998dde2.mp4"
    },
    "resolution": "768P",
    "duration": 4,
    "usage": {
      "total_seconds": 4,
      "input_seconds": 0,
      "output_seconds": 4,
      "input_image_count": 0
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}
```

[Abrir o resultado de vídeo real desta tarefa](https://cdn.acedata.cloud/assets/examples/minimax/f5977217-ed2c-40da-adbe-93d08235618f-b080c998dde2.mp4)

## Status da tarefa

| `status` | Significado | Tratamento pelo cliente |
| - | - | - |
| `queued` | Entrou na fila, aguardando execução | Continuar a consulta |
| `running` | Está sendo gerado | Continuar a consulta |
| `succeeded` | Geração bem-sucedida | Ler `task.content.url`, interromper a consulta |
| `failed` | Falha na geração | Ler `task.error`, interromper a consulta |
| `cancelled` | A tarefa foi cancelada | Interromper a consulta |

`succeeded`, `failed` e `cancelled` são todos estados terminais. Não continue consultando após entrar em um estado terminal.

## Campos de resposta de task

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | string | ID da tarefa |
| `model` | string | Modelo usado pela tarefa, atualmente `MiniMax-H3` |
| `status` | string | Status atual da tarefa |
| `error.code` | string | Código de erro de falha, retornado somente em caso de falha |
| `error.message` | string | Motivo da falha, retornado somente em caso de falha |
| `created_at` | integer | Horário de criação, timestamp Unix em segundos |
| `updated_at` | integer | Horário da atualização de status mais recente, timestamp Unix em segundos |
| `content.url` | string | Endereço do vídeo após o sucesso |
| `resolution` | string | Resolução de saída, `768P` ou `2K` |
| `duration` | integer | Duração do vídeo de saída, em segundos |
| `usage.total_seconds` | integer | Quantidade total faturável, igual à soma dos segundos de vídeo de entrada e de saída |
| `usage.input_seconds` | integer | Quantidade faturável gerada pela entrada de vídeo de referência |
| `usage.output_seconds` | integer | Quantidade faturável gerada pelo vídeo de saída |
| `usage.input_image_count` | integer | Número de imagens de entrada nas estatísticas de cobrança |
| `ratio` | string | Proporção real de largura e altura da saída; ao usar `adaptive`, prevalece o resultado aqui |
| `task_type` | string | Para tarefas de geração de vídeo, é `generation` |
| `modality` | string | Para tarefas de vídeo, é `video` |

## Exemplo completo de polling em Python

O código abaixo lê o Token a partir da variável de ambiente e consulta uma vez a cada 10 segundos após criar a tarefa:

```python theme={null}
import os
import time

import requests

BASE_URL = "https://api.acedata.cloud"
HEADERS = {
    "Authorization": f"Bearer {os.environ['ACEDATACLOUD_API_KEY']}",
    "Content-Type": "application/json",
}

create_response = requests.post(
    f"{BASE_URL}/minimax/videos",
    headers=HEADERS,
    json={
        "model": "MiniMax-H3",
        "content": [
            {
                "type": "text",
                "text": "清晨的海边，一艘白色帆船驶过平静海面，镜头缓慢横移",
            }
        ],
        "resolution": "768P",
        "duration": 4,
        "ratio": "16:9",
    },
    timeout=30,
)
create_response.raise_for_status()
task_id = create_response.json()["task_id"]

while True:
    time.sleep(10)
    query_response = requests.post(
        f"{BASE_URL}/minimax/tasks",
        headers=HEADERS,
        json={"action": "retrieve", "id": task_id},
        timeout=30,
    )
    query_response.raise_for_status()
    task = query_response.json()["task"]
    print(f"task={task_id} status={task['status']}")

    if task["status"] == "succeeded":
        print(f"video_url={task['content']['url']}")
        break
    if task["status"] in ("failed", "cancelled"):
        raise RuntimeError(task.get("error") or task["status"])
```

Em ambientes de produção, deve-se definir um tempo limite total para o polling e usar recuo exponencial para `429` e `5xx` temporários. Um tempo limite de rede não equivale a uma falha na geração; é possível continuar consultando com o mesmo `task_id`.

## Consulta em lote

Especifique vários IDs de tarefa:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/minimax/tasks' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "retrieve_batch",
    "ids": ["TASK_ID_1", "TASK_ID_2"],
    "offset": 0,
    "limit": 20
  }'
```

Liste tarefas paginadas por intervalo de tempo:

```json theme={null}
{
  "action": "retrieve_batch",
  "created_at_min": 1786000000,
  "created_at_max": 1786200000,
  "offset": 0,
  "limit": 20
}
```

Os `items` na resposta em lote usam os mesmos campos de task da consulta de tarefa única, e `total` é o número total de tarefas correspondentes às condições de filtragem:

```json theme={null}
{
  "items": [
    {
      "id": "TASK_ID_1",
      "model": "MiniMax-H3",
      "status": "running",
      "resolution": "2K",
      "duration": 5,
      "ratio": "adaptive",
      "task_type": "generation",
      "modality": "video"
    }
  ],
  "total": 1
}
```

A janela de consulta de tarefas é dos últimos 7 dias. `task_id` além dessa janela pode retornar uma tarefa inválida; os sistemas de negócio devem salvar o ID ao criar uma tarefa e persistir a URL do resultado prontamente após o sucesso.

## Cancelar ou excluir uma tarefa

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/minimax/tasks' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "delete",
    "id": "YOUR_TASK_ID"
  }'
```

A ação depende do estado atual da tarefa:

| Estado atual | Comportamento |
| - | - |
| `queued` | Cancela uma tarefa que ainda não foi iniciada |
| `succeeded` | Exclui o registro da tarefa |
| `failed` | Exclui o registro da tarefa |
| `running` | Não é permitido excluir ou cancelar, retorna um erro |
| `cancelled` | Não é permitido repetir a operação, retorna um erro |

Exemplo de exclusão bem-sucedida:

```json theme={null}
{
  "id": "YOUR_TASK_ID",
  "deleted": true
}
```

Excluir o registro da tarefa não reverte cobranças já concluídas, nem pode garantir que cópias de vídeo já salvas sejam excluídas simultaneamente.

## Respostas de falha e diagnóstico

Tarefas com falha ainda retornam o objeto task com HTTP 200, e o motivo é fornecido em `task.error`:

```json theme={null}
{
  "task": {
    "id": "YOUR_TASK_ID",
    "model": "MiniMax-H3",
    "status": "failed",
    "error": {
      "code": "1026",
      "message": "video description contains sensitive content"
    },
    "task_type": "generation",
    "modality": "video"
  }
}
```

Quando a própria interface retorna `400`, deve-se verificar `action` e os parâmetros de condição; `401` indica Token inválido, `429` indica consultas muito frequentes e `500` indica que o serviço está temporariamente indisponível. Tarefas com falha de geração não são cobradas; tarefas bem-sucedidas registram o uso de acordo com o `usage` final.


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