Predicciones

Comprende las tareas de generación asíncronas — enviar, consultar y obtener resultados

¿Qué son las predicciones?

Cuando envías una solicitud de generación de imagen o video a Atlas Cloud, la tarea no se completa de inmediato. En su lugar, recibes un ID de predicción que puedes usar para rastrear el progreso de la tarea y obtener el resultado cuando esté listo.

Este patrón asíncrono se utiliza para todas las tareas de generación que no son LLM (imágenes, videos, etc.) porque estas tareas pueden tardar desde unos pocos segundos hasta varios minutos en completarse.

Ciclo de vida de la predicción

┌─────────┐     ┌────────────┐     ┌───────────┐
│ Submit   │ ──→ │ Processing │ ──→ │ Completed │
│ Task     │     │            │     │           │
└─────────┘     └────────────┘     └───────────┘
                      │
                      ▼
                ┌───────────┐
                │  Failed   │
                └───────────┘

Valores de estado:

processing — La tarea está siendo procesada por el modelo
completed — La generación ha terminado, la salida está disponible
failed — La generación falló, los detalles del error están disponibles

Enviar una tarea

Generación de imágenes

import requests

response = requests.post(
    "https://api.atlascloud.ai/api/v1/model/generateImage",
    headers={
        "Authorization": "Bearer your-api-key",
        "Content-Type": "application/json"
    },
    json={
        "model": "seedream-3.0",
        "prompt": "A beautiful mountain landscape at golden hour"
    }
)

data = response.json()
prediction_id = data.get("predictionId")
print(f"Task submitted: {prediction_id}")

Generación de videos

response = requests.post(
    "https://api.atlascloud.ai/api/v1/model/generateVideo",
    headers={
        "Authorization": "Bearer your-api-key",
        "Content-Type": "application/json"
    },
    json={
        "model": "kling-v2.0",
        "prompt": "Ocean waves crashing on a rocky shore at sunset"
    }
)

data = response.json()
prediction_id = data.get("predictionId")

Consultar resultados

Usa el ID de predicción para verificar el estado de la tarea y obtener la salida:

import requests
import time

def wait_for_result(prediction_id, api_key, interval=5, timeout=300):
    """Consulta el resultado de la generación con tiempo de espera."""
    elapsed = 0
    while elapsed < timeout:
        response = requests.get(
            f"https://api.atlascloud.ai/api/v1/model/getResult?predictionId={prediction_id}",
            headers={"Authorization": f"Bearer {api_key}"}
        )
        result = response.json()
        status = result.get("status")

        if status == "completed":
            return result.get("output")
        elif status == "failed":
            raise Exception(f"Generation failed: {result.get('error')}")

        print(f"Status: {status} ({elapsed}s elapsed)")
        time.sleep(interval)
        elapsed += interval

    raise TimeoutError(f"Task did not complete within {timeout}s")

# Uso
output = wait_for_result("your-prediction-id", "your-api-key")
print(f"Result: {output}")

Ejemplo en Node.js

async function waitForResult(predictionId, apiKey, interval = 5000, timeout = 300000) {
  const startTime = Date.now();

  while (Date.now() - startTime < timeout) {
    const response = await fetch(
      `https://api.atlascloud.ai/api/v1/model/getResult?predictionId=${predictionId}`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );
    const result = await response.json();

    if (result.status === "completed") return result.output;
    if (result.status === "failed") throw new Error(`Failed: ${result.error}`);

    console.log(`Status: ${result.status}`);
    await new Promise((r) => setTimeout(r, interval));
  }

  throw new Error("Timeout");
}

const output = await waitForResult("your-prediction-id", "your-api-key");
console.log(`Result: ${output}`);

Ejemplo con cURL

curl "https://api.atlascloud.ai/api/v1/model/getResult?predictionId=your-prediction-id" \
  -H "Authorization: Bearer your-api-key"

Mejores prácticas de polling

Comienza con intervalos más largos: Usa intervalos de 5 segundos para generación de video, intervalos de 2 segundos para generación de imágenes
Establece un tiempo de espera: Siempre establece un tiempo de espera máximo para evitar polling infinito
Maneja los fallos correctamente: Verifica el estado failed y maneja los errores apropiadamente
Registra el progreso: Imprime actualizaciones de estado para que los usuarios sepan que la tarea sigue en ejecución

Tiempos típicos de generación

Tipo de tarea	Tiempo típico
Generación de imágenes	2–10 segundos
Generación de videos	30 segundos – 3 minutos
Imagen a video	30 segundos – 3 minutos
Herramientas de imagen (mejora, etc.)	5–15 segundos

Los tiempos reales varían según el modelo, los parámetros (resolución, duración) y la carga actual.

Manejo de errores

Cuando una predicción falla, el resultado incluye un mensaje de error:

{
  "status": "failed",
  "error": "Invalid parameter: resolution not supported by this model"
}

Razones comunes de fallo:

Parámetros de modelo inválidos
URL de imagen de entrada inaccesible
El prompt contiene contenido no permitido
Saldo insuficiente en la cuenta

Consulta la Referencia API para documentación completa de códigos de error.

En esta página