予測 | Atlas Cloud ドキュメント

非同期生成タスクの理解 — 送信、ポーリング、結果の取得

予測とは？

Atlas Cloud に画像や動画の生成リクエストを送信すると、タスクはすぐには完了しません。代わりに、タスクの進捗を追跡し、完了時に結果を取得するために使用できる 予測 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"]

結果のポーリング

予測 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 リファレンスをご覧ください。

予測

目次