Предсказания

Асинхронные задачи генерации — отправка, опрос и получение результатов

Что такое предсказания?

Когда вы отправляете запрос на генерацию изображения или видео в Atlas Cloud, задача не завершается мгновенно. Вместо этого вы получаете prediction ID, который можно использовать для отслеживания прогресса задачи и получения результата, когда он будет готов.

Этот асинхронный паттерн используется для всех задач генерации, кроме LLM (изображения, видео и т.д.), поскольку выполнение этих задач может занять от нескольких секунд до нескольких минут.

Жизненный цикл предсказания

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

Значения статусов:

processing — Задача обрабатывается моделью
completed — Генерация завершена, результат доступен
failed — Генерация не удалась, доступны детали ошибки

Отправка задачи

Генерация изображения

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

Генерация видео

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

Опрос результатов

Используйте prediction ID для проверки статуса задачи и получения результата:

import requests
import time

def wait_for_result(prediction_id, api_key, interval=5, timeout=300):
    """Опрос результата генерации с таймаутом."""
    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")

# Использование
output = wait_for_result("your-prediction-id", "your-api-key")
print(f"Result: {output}")

Пример 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}`);

Пример cURL

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

Лучшие практики опроса

Начинайте с более длинных интервалов: Используйте 5-секундные интервалы для генерации видео, 2-секундные для генерации изображений
Устанавливайте таймаут: Всегда задавайте максимальное время ожидания, чтобы избежать бесконечного опроса
Обрабатывайте ошибки корректно: Проверяйте статус failed и обрабатывайте ошибки соответствующим образом
Логируйте прогресс: Выводите обновления статуса, чтобы пользователи знали, что задача ещё выполняется

Типичное время генерации

Тип задачи	Типичное время
Генерация изображений	2–10 секунд
Генерация видео	30 секунд – 3 минуты
Изображение в видео	30 секунд – 3 минуты
Инструменты изображений (масштабирование и т.д.)	5–15 секунд

Фактическое время зависит от модели, параметров (разрешение, длительность) и текущей нагрузки.

Обработка ошибок

Когда предсказание не удаётся, результат содержит сообщение об ошибке:

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

Частые причины ошибок:

Неверные параметры модели
Недоступный URL входного изображения
Промпт содержит запрещённый контент
Недостаточный баланс аккаунта

Полную документацию по кодам ошибок см. в Справочнике API.

Содержание