Cloudflare Workers cron job: AI 영상 예약 실행

Cloudflare Workers의 cron job은 Cron Trigger입니다. Wrangler 파일의 triggers.crons 아래에 cron 표현식을 적고 scheduled() 핸들러를 export하면, Cloudflare가 그 스케줄에 따라 UTC 기준으로 핸들러를 실행합니다. 여기서 AI 영상을 시작하려면 핸들러가 controller.scheduledTime으로 키를 만든 API 호출 하나를 웹훅 URL과 함께 보내고 바로 반환합니다. 완성된 영상은 나중에 Worker 라우트로 도착합니다.

Cloudflare 관련 내용은 Cloudflare의 Cron Triggers, Scheduled 핸들러, 한도, 시크릿 페이지에서, Sume 관련 내용은 Format 호출하기 (영문)와 실행과 결과 (영문)에서 가져왔습니다. 모두 2026-09-27에 확인했습니다. Sume에는 Cloudflare 전용 커넥터가 없으며, Worker가 HTTPS로 직접 호출합니다. Vercel에서 쓰는 같은 패턴은 Vercel Cron Jobs: 매일 Sume API 호출하기에서 다룹니다.

Worker에 Cron Trigger를 어떻게 추가하나요?

핸들러와 스케줄, 두 가지가 필요합니다. Cloudflare는 트리거될 때마다 scheduled(controller, env, ctx)를 호출합니다. controller.cron은 이번 호출을 일으킨 표현식이고, controller.scheduledTime은 이벤트가 예약된 시각으로, UTC 기준 epoch 이후의 밀리초 값입니다. 스케줄은 Wrangler 파일에 적습니다. 예를 들어 매일 09:00 UTC라면 [triggers] 아래에 crons = ["0 9 * * *"]를 둡니다. Wrangler로 Worker를 관리한다면 Cloudflare는 Cron Triggers를 그 파일로만 관리하라고 안내하며, 배포할 때마다 이전 트리거가 배열에 있는 트리거로 교체됩니다.

scheduled 핸들러는 영상 API에 무엇을 보내야 하나요?

POST /v1/formats/{handle}/{slug}/runs 요청 하나입니다. 이 요청은 Format이라고 부르는 저장된 Sume 레시피의 실행을 시작하며, Format은 Sume Format이란?에서 설명합니다. 키는 npx wrangler secret put SUME_API_KEY로 저장하세요. 시크릿은 암호화된 값이며 env에서 읽습니다. Idempotency-Key와 본문은 모두 Date.now()가 아니라 예약된 시각으로 만드세요. 그래야 같은 회차가 반복되어도 똑같은 요청을 보냅니다. 생성 요청은 곧바로 응답합니다. 새 실행이면 202, 재전송이면 200입니다.

export default {
  async scheduled(controller, env, ctx) {
    // The slot this event was scheduled for, not the moment it ran
    const slot = new Date(controller.scheduledTime).toISOString();
    const res = await fetch("https://api.sume.com/v1/formats/acme/daily-recap/runs", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${env.SUME_API_KEY}`,
        "Content-Type": "application/json",
        "Idempotency-Key": `daily-recap-${slot}`,
      },
      body: JSON.stringify({
        input: { slot },
        communication: { webhook_url: "https://video.example.com/hooks/sume" },
      }),
    });
    const { data, error } = await res.json();
    if (!res.ok) throw new Error(`Sume answered ${res.status} ${error?.code}`);
    console.log(`run ${data.id}, replay: ${data.idempotency_hit}`);
  },
};

같은 회차에 핸들러가 두 번 실행되면 어떻게 되나요?

원인이 무엇이든 키 덕분에 반복은 해가 없습니다. 일부러 회차를 다시 실행할 수도 있습니다. 로컬 개발에서는 /cdn-cgi/local/scheduled 라우트가 controller.scheduledTime을 덮어쓰는 time 파라미터를 받으며, 이때 핸들러는 실제 API를 호출합니다. cron 핸들러에서 중요한 Sume의 멱등성 규칙은 두 가지입니다.

• 같은 키, 같은 본문: 원래 영수증과 idempotency_hit: true가 담긴 200이 돌아옵니다. 두 번째 실행도, 두 번째 청구도 없습니다.
• 같은 키, 다른 본문: 409 idempotency_conflict가 돌아오고 아무것도 실행되지 않습니다. communication.webhook_url은 본문의 일부이므로 이 값도 고정해 두세요.
• 같은 순간에 도착한 두 요청이나 실패한 생성 요청 뒤의 재시도 같은 나머지 경우는 AI 영상 API 멱등성 키에서 다룹니다.

Worker가 영상이 끝날 때까지 기다려야 하나요?

아닙니다. cron 호출에 주어지는 wall time은 최대 15분이며, 런타임은 그 한도까지만 핸들러의 promise를 기다립니다. 롱폼 영상은 15분에서 30분이 걸리는 작업이고, Sume 실행은 created_at으로부터 90분까지 이어질 수 있으며 그 뒤에는 failed로 강제 종료됩니다. Worker가 지켜보기를 멈춰도 실행과 그 지출은 멈추지 않습니다.

대신 Sume가 여러분을 호출하게 하세요. 실행이 완료되거나 실패하면 communication.webhook_url로 서명된 format.run.terminal POST가 한 번 전송되며, 취소된 실행은 아무것도 보내지 않습니다. 그 POST를 검증하고 작업을 Queue로 넘기는 fetch() 쪽은 Cloudflare Workers 웹훅을 Queue로에서 보여 줍니다.

시계 말고는 작업을 일으키는 것이 없고 실행에 여러분 쪽 데이터가 필요 없다면, Worker가 아예 필요 없을 수도 있습니다. Sume 자체의 Scheduled 기능이 저장된 자동화를 정해진 주기로 실행하며, 이는 AI 영상 에이전트 스케줄 실행에서 설명합니다.