Skip to main content

​
Обзор

Вместо того чтобы многократно опрашивать GET /jobs/{id}, вы можете указать URL webhook’а и получать POST-запрос, когда ваше задание завершается. Это эффективнее и уменьшает количество ненужных вызовов API.

​
Использование webhooks

Добавьте заголовок X-Webhook-URL к любому запросу на генерацию. Когда задание достигнет терминального состояния (completed, failed или cancelled), API отправит POST-запрос на ваш URL с полными данными задания. 
// 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-запроса

Когда задание завершится, ваш URL webhook’а получит 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’ов для отладки

​
Webhooks против опроса

ПодходПлюсыМинусы
WebhooksУведомления в реальном времени, меньше вызовов APIНужен публичный эндпоинт
ОпросРаботает везде, сервер не нуженБольше вызовов API, небольшая задержка
Используйте webhooks, если у вас есть сервер, который может принимать HTTP-запросы. Используйте опрос для клиентских приложений или когда вы не можете предоставить публичный эндпоинт.

​
Следующие шаги

Жизненный цикл задания

Узнайте о состояниях заданий и опросе статуса

Примеры кода

Полные примеры с обработкой webhook’ов