Reduce Friction and Latency for Long-Running Jobs with Webhooks in Gemini API

Hero

#新しい方法: Webhook

Webhookを利用すると、処理の開始ステップと結果の取得ステップを完全に分離できる。リクエストを投げると同時に、コールバックURLを渡すだけでよい。

// Modern Webhook Approach: Initiating the job
async function initiateVideoProcessing(fileId) {
  await fetch('https://api.gemini.com/v1/jobs/analyze', {
    method: 'POST',
    body: JSON.stringify({ 
      fileId: fileId, 
      prompt: "Extract key moments.",
      webhook_url: "https://api.ichiban-tools.com/webhooks/gemini/video-complete"
    })
  });
  // Return immediately; the user can continue navigating the app.
}

そして、サーバー側に結果を受け取るための専用エンドポイントを用意する。

// Express.js Webhook Receiver
app.post('/webhooks/gemini/video-complete', express.json(), (req, res) => {
  // 1. Verify the signature to ensure the request actually came from Google
  if (!verifyGeminiSignature(req)) {
    return res.status(401).send("Unauthorized");
  }

  const { jobId, status, result, error } = req.body;
  
  if (status === "COMPLETED") {
    // 2. Process the results asynchronously (e.g., save to DB, notify user via WebSocket)
    database.saveAnalysis(jobId, result);
    notifier.sendWebSocketMessage(jobId, "Analysis Complete!");
  } else if (status === "FAILED") {
    errorHandler.logAndAlert(jobId, error);
  }

  // 3. Acknowledge receipt quickly to prevent webhook retries
  res.status(200).send("OK");
});