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

# Guía de integración de la API de consulta de tareas MiniMax H3

> Minimax API guide - Ace Data Cloud

Este artículo presenta la integración y el uso de la API de consulta de tareas MiniMax H3. Esta interfaz se utiliza para consultar, listar por lotes o eliminar tareas asíncronas creadas por la [API de generación de video MiniMax H3](https://platform.acedata.cloud/documents/minimax-videos-integration).

## Proceso de solicitud

Para utilizar la API de consulta de tareas MiniMax H3, primero obtenga su API Token en la [Consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) y consérvelo como respaldo.

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

Si aún no ha iniciado sesión o no se ha registrado, será redirigido automáticamente a la página de inicio de sesión para invitarle a registrarse e iniciar sesión; al completarlo, volverá automáticamente a la página actual.

**Un solo API Token puede invocar todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio.** La primera solicitud incluye crédito gratuito, que permite una experiencia gratuita; cuando el crédito sea insuficiente, puede recargar saldo general en la [consola](https://platform.acedata.cloud/console/coin).

> 📘 Documentación completa: [API de consulta de tareas MiniMax H3 →](https://platform.acedata.cloud/documents/minimax-tasks-integration)

Al consultar una tarea, debe utilizar el mismo Token con el que se creó dicha tarea. Se recomienda guardar el Token como una variable de entorno, y no escribirlo en el código fuente ni enviarlo al repositorio de versiones:

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

## Resumen de la interfaz

* **Base URL**：`https://api.acedata.cloud`
* **Endpoint**：`POST /minimax/tasks`
* **Método de autenticación**：Incluir `authorization: Bearer {token}` en el HTTP Header
* **Encabezados de solicitud**：
  * `accept: application/json`
  * `content-type: application/json`
* **Consultar una sola tarea**：`action=retrieve`, pasar `id`
* **Consultar tareas por lotes**：`action=retrieve_batch`, se puede filtrar por ID de tarea, intervalo de tiempo y condiciones de paginación
* **Eliminar tarea**：`action=delete`, pasar `id`
* **Descripción de facturación**：La consulta de tareas es gratuita y no generará cargos duplicados

Después de crear un video, debe guardar el `task_id`. Se recomienda consultar aproximadamente cada 10 segundos hasta que la tarea entre en un estado terminal.

## Parámetros de solicitud

| Parámetro | Tipo | Obligatorio condicionalmente | Acción aplicable | Descripción |
| - | - | - | - | - |
| `action` | string | No | Todas | `retrieve`, `retrieve_batch` o `delete`; el valor predeterminado es `retrieve` |
| `id` | string | Obligatorio condicionalmente | `retrieve`, `delete` | ID de una sola tarea |
| `ids` | string\[] | No | `retrieve_batch` | Solo devuelve los ID de tareas especificados; si se omite, lista las tareas según otras condiciones |
| `limit` | integer | No | `retrieve_batch` | Cantidad máxima de tareas devueltas en esta ocasión |
| `offset` | integer | No | `retrieve_batch` | Cantidad de tareas omitidas de la lista de resultados, para paginación |
| `created_at_min` | number | No | `retrieve_batch` | Límite inferior de tiempo de creación, marca de tiempo Unix, en segundos |
| `created_at_max` | number | No | `retrieve_batch` | Límite superior de tiempo de creación, marca de tiempo Unix, en segundos |

Los usos de las tres acciones son los siguientes:

| `action` | Uso | Parámetros necesarios | Estructura de respuesta |
| - | - | - | - |
| `retrieve` | Consultar el estado y resultado de una tarea | `id` | `{ "task": {...} }` |
| `retrieve_batch` | Consultar por lotes según ID de tarea, tiempo y condiciones de paginación | `ids` opcional, intervalo de tiempo, `offset`, `limit` | `{ "items": [...], "total": number }` |
| `delete` | Cancelar o eliminar el registro de una tarea según su estado actual | `id` | `{ "id": "...", "deleted": true }` |

## Consultar una sola tarea

```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"
  }'
```

A continuación se muestra la respuesta de una tarea exitosa real:

```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 el resultado de video real de esta tarea](https://cdn.acedata.cloud/assets/examples/minimax/f5977217-ed2c-40da-adbe-93d08235618f-b080c998dde2.mp4)

## Estado de la tarea

| `status` | Significado | Procesamiento del cliente |
| - | - | - |
| `queued` | Ha entrado en la cola y espera ejecución | Continuar sondeando |
| `running` | Se está generando | Continuar sondeando |
| `succeeded` | Generación exitosa | Leer `task.content.url`, detener el sondeo |
| `failed` | Error de generación | Leer `task.error`, detener el sondeo |
| `cancelled` | La tarea ha sido cancelada | Detener el sondeo |

`succeeded`, `failed` y `cancelled` son todos estados terminales. No continúe sondeando después de entrar en un estado terminal.

## Campos de respuesta de task

| Campo | Tipo | Descripción |
| - | - | - |
| `id` | string | ID de la tarea |
| `model` | string | El modelo utilizado por la tarea, actualmente `MiniMax-H3` |
| `status` | string | Estado actual de la tarea |
| `error.code` | string | Código de error de fallo, devuelto solo en caso de fallo |
| `error.message` | string | Motivo del fallo, devuelto solo en caso de fallo |
| `created_at` | integer | Hora de creación, marca de tiempo Unix, en segundos |
| `updated_at` | integer | Hora de la actualización de estado más reciente, marca de tiempo Unix, en segundos |
| `content.url` | string | Dirección del video después del éxito |
| `resolution` | string | Resolución de salida, `768P` o `2K` |
| `duration` | integer | Duración del video de salida, en segundos |
| `usage.total_seconds` | integer | Cantidad total facturada, igual a la suma de los segundos de video de entrada y los segundos de salida |
| `usage.input_seconds` | integer | Cantidad facturada generada por la entrada de video de referencia |
| `usage.output_seconds` | integer | Cantidad facturada generada por el video de salida |
| `usage.input_image_count` | integer | Cantidad de imágenes de entrada en las estadísticas de facturación |
| `ratio` | string | Relación de aspecto de salida real; al usar `adaptive`, prevalece el resultado de aquí |
| `task_type` | string | La tarea de generación de video es `generation` |
| `modality` | string | La tarea de video es `video` |

## Ejemplo completo de sondeo en Python

El siguiente código lee el Token desde una variable de entorno, crea una tarea y luego consulta una vez cada 10 segundos:

```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"])
```

El entorno de producción debe establecer un tiempo de espera total para el sondeo y usar retroceso exponencial para `429` y `5xx` temporales. Un tiempo de espera de red no equivale a un fallo de generación; se puede continuar consultando con el mismo `task_id`.

## Consulta por lotes

Especifique múltiples ID de tarea:

```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
  }'
```

Enumere las tareas por páginas según el intervalo de tiempo:

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

Los `items` en la respuesta por lotes usan los mismos campos de task que la consulta de una sola tarea, y `total` es el número total de tareas que coinciden con los criterios de filtrado:

```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
}
```

La ventana de consulta de tareas corresponde a los últimos 7 días. Los `task_id` que excedan esta ventana pueden devolver una tarea no válida; el sistema de negocio debe guardar el ID al crear la tarea y persistir oportunamente la URL del resultado tras el éxito.

## Cancelar o eliminar una tarea

```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"
  }'
```

La acción depende del estado actual de la tarea:

| Estado actual | Comportamiento |
| - | - |
| `queued` | Cancela la tarea que aún no ha comenzado |
| `succeeded` | Elimina el registro de la tarea |
| `failed` | Elimina el registro de la tarea |
| `running` | No se permite eliminar ni cancelar; devuelve un error |
| `cancelled` | No se permite repetir la operación; devuelve un error |

Ejemplo de eliminación exitosa:

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

Eliminar el registro de la tarea no revertirá la facturación ya completada, ni puede garantizar que las copias de vídeo ya guardadas se eliminen al mismo tiempo.

## Respuestas de fallo y solución de problemas

Las tareas fallidas aún devuelven un objeto task con HTTP 200, e indican la causa en `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"
  }
}
```

Cuando la propia interfaz devuelve `400`, se deben comprobar `action` y los parámetros de condición; `401` indica que el Token no es válido, `429` indica que las consultas son demasiado frecuentes y `500` indica que el servicio no está disponible temporalmente. Las tareas con fallo de generación no se facturan; las tareas exitosas registran el uso según el `usage` final.


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