Predizioni

Comprendi le attivita di generazione asincrone — invia, interroga e ottieni risultati

Cosa sono le predizioni?

Quando invii una richiesta di generazione di immagine o video ad Atlas Cloud, l'attivita non viene completata immediatamente. Invece, ricevi un ID di predizione che puoi usare per tracciare il progresso dell'attivita e ottenere il risultato quando e pronto.

Questo pattern asincrono viene utilizzato per tutte le attivita di generazione non-LLM (immagini, video, ecc.) perche queste attivita possono richiedere da pochi secondi a diversi minuti per essere completate.

Ciclo di vita della predizione

+----------+     +------------+     +-----------+
| Submit   | --> | Processing | --> | Completed |
| Task     |     |            |     |           |
+----------+     +------------+     +-----------+
                      |
                      v
                +-----------+
                |  Failed   |
                +-----------+

Valori di stato:

processing — L'attivita viene elaborata dal modello
completed — La generazione e completata, l'output e disponibile
failed — La generazione e fallita, i dettagli dell'errore sono disponibili

Inviare un'attivita

Generazione di immagini

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["data"]["id"]
print(f"Task submitted: {prediction_id}")

Generazione di video

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["data"]["id"]

Interrogare i risultati

Usa l'ID di predizione per verificare lo stato dell'attivita e ottenere l'output:

import requests
import time

def wait_for_result(prediction_id, api_key, interval=5, timeout=300):
    """Interroga il risultato della generazione con timeout."""
    elapsed = 0
    while elapsed < timeout:
        response = requests.get(
            f"https://api.atlascloud.ai/api/v1/model/prediction/{prediction_id}",
            headers={"Authorization": f"Bearer {api_key}"}
        )
        result = response.json()
        status = result["data"]["status"]

        if status == "completed":
            return result["data"]["outputs"][0]
        elif status == "failed":
            raise Exception(f"Generation failed: {result['data'].get('error')}")

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

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

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

Esempio in 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/prediction/${predictionId}`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );
    const result = await response.json();
    const status = result.data.status;

    if (status === "completed") return result.data.outputs[0];
    if (status === "failed") throw new Error(`Failed: ${result.data.error}`);

    console.log(`Status: ${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}`);

Esempio con cURL

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

Migliori pratiche di polling

Inizia con intervalli piu lunghi: Usa intervalli di 5 secondi per la generazione di video, intervalli di 2 secondi per la generazione di immagini
Imposta un timeout: Imposta sempre un tempo massimo di attesa per evitare il polling infinito
Gestisci i fallimenti correttamente: Controlla lo stato failed e gestisci gli errori in modo appropriato
Registra il progresso: Stampa aggiornamenti di stato cosi gli utenti sanno che l'attivita e ancora in esecuzione

Tempi di generazione tipici

Tipo di attivita	Tempo tipico
Generazione di immagini	2-10 secondi
Generazione di video	30 secondi - 3 minuti
Immagine a video	30 secondi - 3 minuti
Strumenti immagine (miglioramento, ecc.)	5-15 secondi

I tempi effettivi variano a seconda del modello, dei parametri (risoluzione, durata) e del carico attuale.

Gestione degli errori

Quando una predizione fallisce, il risultato include un messaggio di errore:

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

Ragioni comuni di fallimento:

Parametri del modello non validi
URL dell'immagine di input non accessibile
Il prompt contiene contenuti non consentiti
Saldo dell'account insufficiente

Consulta il Riferimento API per la documentazione completa dei codici di errore.

In questa pagina