预测任务

什么是预测任务？

当你向 Atlas Cloud 提交图像或视频生成请求时，任务不会立即完成。你会收到一个 prediction ID，可以用它来跟踪任务进度并在完成后获取结果。

这种异步模式适用于所有非 LLM 的生成任务（图像、视频等），因为这些任务可能需要几秒到几分钟不等的时间来完成。

预测任务生命周期

┌─────────┐     ┌────────────┐     ┌───────────┐
│ 提交     │ ──→ │ 处理中     │ ──→ │ 已完成    │
│ 任务     │     │            │     │           │
└─────────┘     └────────────┘     └───────────┘
                      │
                      ▼
                ┌───────────┐
                │  失败     │
                └───────────┘

状态值：

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 秒

实际耗时因模型、参数（分辨率、时长）和当前负载而异。

错误处理

当预测任务失败时，结果中会包含错误信息：

{
  "data": {
    "id": "prediction-id",
    "status": "failed",
    "error": "Invalid parameter: resolution not supported by this model",
    "outputs": []
  }
}

常见失败原因：

无效的模型参数
输入图片 URL 无法访问
提示词包含不允许的内容
账户余额不足

完整的错误码文档请参阅 API 参考。

本页目录