GET /task/:taskId | ZUI GEN API Docs

GET/api/v1/task/:taskId

Consulta el estado de una tarea de generacion y obtiene los resultados cuando esta completada.

Path Parameters

Parametro	Tipo	Descripcion
`taskId`	string (UUID)	ID de la tarea obtenido de POST /generate

Ejemplo de Request

curl https://gen.zui.es/api/v1/task/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

Tarea en proceso

200 OK - Processingjson

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "flux/schnell",
  "category": "image",
  "status": "processing",
  "input": {
    "prompt": "A beautiful sunset over the ocean",
    "aspect_ratio": "16:9"
  },
  "output_urls": null,
  "error": null,
  "credits_consumed": 5,
  "created_at": "2025-01-01T12:00:00Z",
  "completed_at": null
}

Tarea completada

200 OK - Completedjson

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "flux/schnell",
  "category": "image",
  "status": "completed",
  "input": {
    "prompt": "A beautiful sunset over the ocean",
    "aspect_ratio": "16:9"
  },
  "output_urls": [
    "https://storage.example.com/result-image.png"
  ],
  "error": null,
  "credits_consumed": 5,
  "created_at": "2025-01-01T12:00:00Z",
  "completed_at": "2025-01-01T12:00:15Z"
}

Tarea fallida

200 OK - Failedjson

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "flux/schnell",
  "category": "image",
  "status": "failed",
  "input": {
    "prompt": "A beautiful sunset over the ocean"
  },
  "output_urls": null,
  "error": "Content moderation rejected the prompt",
  "credits_consumed": 0,
  "created_at": "2025-01-01T12:00:00Z",
  "completed_at": "2025-01-01T12:00:05Z"
}

Estados de Tarea

Status	Descripcion	output_urls
`processing`	La tarea esta siendo procesada	null
`completed`	La generacion termino exitosamente	Array de URLs
`failed`	La generacion fallo	null

Campos de Respuesta

Campo	Tipo	Descripcion
`task_id`	string	UUID de la tarea
`model`	string	Identificador del modelo usado
`category`	string	"image", "video" o "audio"
`status`	string	Estado actual de la tarea
`input`	object	Parametros de entrada usados
`output_urls`	string[] \| null	URLs de los archivos generados
`error`	string \| null	Mensaje de error si fallo
`credits_consumed`	number	Creditos consumidos (0 si fallo)
`created_at`	string	Fecha de creacion (ISO 8601)
`completed_at`	string \| null	Fecha de finalizacion (ISO 8601)

Estrategia de Polling

Como las generaciones pueden tardar desde segundos hasta varios minutos, recomendamos implementar un sistema de polling con las siguientes caracteristicas:

Intervalo inicial: 2 segundos
Incrementar gradualmente hasta 10 segundos
Timeout maximo: 10 minutos para videos largos
Detener cuando status sea "completed" o "failed"

Ejemplo de pollingjavascript

async function waitForResult(taskId, apiKey) {
  const maxAttempts = 60; // 10 minutes max
  let attempts = 0;
  let interval = 2000; // Start with 2 seconds
  while (attempts < maxAttempts) {
    const response = await fetch(
      `https://gen.zui.es/api/v1/task/${taskId}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    const task = await response.json();
    if (task.status === 'completed') {
      return task.output_urls;
    }
    if (task.status === 'failed') {
      throw new Error(task.error);
    }
    // Wait and increase interval
    await new Promise(r => setTimeout(r, interval));
    interval = Math.min(interval * 1.5, 10000);
    attempts++;
  }
  throw new Error('Task timed out');
}

Errores

Codigo	HTTP	Descripcion
`TASK_NOT_FOUND`	404	La tarea no existe o no te pertenece
`INTERNAL_ERROR`	500	Error interno del servidor

Nota sobre URLs

Las URLs en output_urls son URLs firmadas temporalmente. Recomendamos descargar o almacenar los resultados en tu propio sistema de almacenamiento si necesitas acceso a largo plazo.