Skip to main content

​
概要

GET /jobs/{id} を繰り返しポーリングする代わりに、Webhook URL を指定して、ジョブ完了時に POST リクエストを受け取ることができます。これはより効率的で、不要な API 呼び出しを削減します。

​
Webhook の使用方法

任意の生成リクエストに X-Webhook-URL ヘッダーを追加します。ジョブが終了状態(completed、failed、または cancelled)に達すると、API は完全なジョブデータとともに指定した URL に POST リクエストを送信します。 
// npm install @krea-ai/sdk
import { Krea } from "@krea-ai/sdk";

const krea = new Krea({ apiKey: process.env.KREA_API_KEY });

const job = await krea.image(
  "bfl/flux-1-dev",
  {
    prompt: "a serene mountain landscape at sunset",
    width: 1024,
    height: 576
  },
  { webhookUrl: "https://your-server.com/webhook" }
);

console.log(`Job ID: ${job.job_id}`);
// Your webhook will receive the results when complete

​
Webhook ペイロード

ジョブが完了すると、Webhook URL は以下のジョブデータとともに POST リクエストを受け取ります: 
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "created_at": "2025-01-15T10:30:00.000Z",
  "completed_at": "2025-01-15T10:30:05.000Z",
  "result": {
    "urls": ["https://..."]
  }
}

​
ベストプラクティス

すぐに応答する - 2xx ステータスコードを速やかに返してください。必要に応じて、Webhook データを非同期で処理してください。
ペイロードを検証する - 結果を処理する前に、job_id が自分が開始したジョブと一致することを確認してください。
  • セキュリティのために HTTPS エンドポイントを使用する
  • 重複配信に備えて冪等性を実装する
  • デバッグのために Webhook 受信をログに記録する

​
Webhook vs ポーリング

アプローチメリットデメリット
Webhookリアルタイム通知、API 呼び出しが少ないパブリックエンドポイントが必要
ポーリングどこでも動作、サーバー不要API 呼び出しが多い、わずかな遅延
HTTP リクエストを受信できるサーバーがある場合は Webhook を使用してください。クライアントサイドアプリケーションやパブリックエンドポイントを公開できない場合はポーリングを使用してください。

​
次のステップ

Job Lifecycle

ジョブの状態とステータスポーリングについて学ぶ

Code Examples

Webhook 処理を含む完全な例を見る