Predições

Entenda as tarefas de geração assíncronas — enviar, consultar e obter resultados

O que são predições?

Quando você envia uma solicitação de geração de imagem ou vídeo ao Atlas Cloud, a tarefa não é concluída imediatamente. Em vez disso, você recebe um ID de predição que pode usar para acompanhar o progresso da tarefa e obter o resultado quando estiver pronto.

Este padrão assíncrono é usado para todas as tarefas de geração que não são LLM (imagens, vídeos, etc.) porque essas tarefas podem levar de alguns segundos a vários minutos para serem concluídas.

Ciclo de vida da predição

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

Valores de status:

processing — A tarefa está sendo processada pelo modelo
completed — A geração foi concluída, a saída está disponível
failed — A geração falhou, os detalhes do erro estão disponíveis

Enviar uma tarefa

Geração de imagens

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}")

Geração de vídeos

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

Consultar resultados

Use o ID de predição para verificar o status da tarefa e obter a saída:

import requests
import time

def wait_for_result(prediction_id, api_key, interval=5, timeout=300):
    """Consultar o resultado da geracao com 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")

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

Exemplo em 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}`);

Exemplo com cURL

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

Melhores práticas de polling

Comece com intervalos maiores: Use intervalos de 5 segundos para geração de vídeo, intervalos de 2 segundos para geração de imagens
Defina um timeout: Sempre defina um tempo máximo de espera para evitar polling infinito
Trate falhas corretamente: Verifique o status failed e trate os erros adequadamente
Registre o progresso: Imprima atualizações de status para que os usuários saibam que a tarefa ainda está em execução

Tempos típicos de geração

Tipo de tarefa	Tempo típico
Geração de imagens	2-10 segundos
Geração de vídeos	30 segundos - 3 minutos
Imagem para vídeo	30 segundos - 3 minutos
Ferramentas de imagem (melhoria, etc.)	5-15 segundos

Os tempos reais variam dependendo do modelo, parâmetros (resolução, duração) e carga atual.

Tratamento de erros

Quando uma predição falha, o resultado inclui uma mensagem de erro:

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

Razões comuns de falha:

Parâmetros de modelo inválidos
URL da imagem de entrada inacessível
O prompt contém conteúdo não permitido
Saldo insuficiente na conta

Consulte a Referência da API para documentação completa de códigos de erro.

On this page