Skip to main content
このガイドでは、novita-gpus SDK を使用して Async Serverless Endpoint を呼び出す方法と、worker handler をカスタマイズする方法を説明します。

1. SDK のインストール

クライアント環境または worker ランタイム環境に SDK をインストールします。

2. SDK でジョブを送信する

novita-gpus SDK のデフォルトリクエスト URL は https://async-public.serverless.novita.ai/v1 です。Endpoint を呼び出すには、API Key を設定し、Endpoint 名を指定してクライアントを作成します。

3. ComfyUI ジョブの例

novitalabs/comfyui-worker:v0.0.1 の場合、ジョブ入力には ComfyUI workflow を含める必要があります。以下の最小例は、テスト済みのケースと一致します。

4. カスタム Handler

worker 側では、novita_gpus.start({"handler": handler}) を呼び出してタスクループを開始します。プラットフォームはタスクデータを handler(job) に渡します。
  • job["id"]: 現在のジョブ ID
  • job["input"]: クライアントによって送信された入力内容
  • handler の戻り値はジョブ出力として使用されます
  • 返された dict に error フィールドが含まれる場合、ジョブは失敗としてマークされます
最小 handler の例:

5. 完全な Worker 例

完全な worker ソースコード、Docker イメージのビルド手順、タスク送信スクリプトについては、Novita GPUs Python examples を参照してください。 このリポジトリには 2 つの例が含まれています。
  • comfyui-worker: handler.py から ComfyUI を実行し、生成された画像を返します。
  • sleep-worker: 指定された時間だけ待機し、JSON 結果を返す最小限の handler.py です。
各サンプルディレクトリには以下が含まれています。
  • handler.py: handler(job) を定義し、novita_gpus.start({"handler": handler}) で worker を開始します。
  • Dockerfile: worker イメージをビルドします。
  • requirements.txt: novita-gpus をインストールします。
  • submit_task.py: novita-gpus クライアント SDK を使用してタスクを送信します。
worker イメージをビルドし、自分の registry にプッシュします。
タスク送信では、Endpoint 名の形式 <endpoint-id>-<app-name> を使用します。 たとえば、Endpoint ID o8UJWkag5WTn と app 名 async から、次のようになります。
submit_task.py の例では、Endpoint ID と app 名を別々に受け取り、最終的な Endpoint 名を組み立てます。
スクリプト内では、組み立てた Endpoint 名を使用して SDK クライアントを作成します。

6. 画像またはファイルを返す

Async Serverless Endpoint status API には出力サイズの制限があります。画像や動画などの大きなファイルについては、まずオブジェクトストレージにアップロードし、出力で URL を返してください。 Endpoint でオブジェクトストレージの環境変数を設定します。
handler で画像をアップロードします。
通常のファイルや bytes をアップロードすることもできます。

7. FAQ

worker で API Key を設定する必要がありますか?

通常は不要です。API Key は主に、クライアントがジョブを送信、照会、キャンセルするために使用されます。

どの handler 戻り値がジョブを失敗としてマークしますか?

handler が error フィールドを含む dict を返すと、ジョブは失敗としてマークされます。
最終更新日 2026年8月10日