영상 생성 API 타임아웃: Sume 대기 상한, SDK 기본값, 만료

Sume에서 영상 생성 호출의 클라이언트 쪽 타임아웃은 여러분의 대기를 끝낼 뿐, Job을 끝내지는 않습니다. sync 제출은 최대 30초까지만 블로킹하고, 지켜보기를 멈춘 Job은 계속 실행되며 계속 과금됩니다. 마감 시간은 분 단위로 직접 정하고(문서는 영상에 20분 정도가 적당하다고 봅니다), 폴링하거나 웹훅을 받으세요. 유료 요청은 다시 제출하지 마세요.

아래 한도는 Sume 문서 Job과 결과 (영문), 실행 기다리기 (영문), 실행과 결과 (영문), 웹훅 (영문)에서 가져왔으며, 모두 2026-09-26에 확인했습니다.

영상 Job과 실행에는 어떤 타임아웃이 적용되나요?

적용되는 한도는 일곱 가지입니다. 이 가운데 작업 자체를 끝내는 것은 Format 실행 만료뿐이고, 나머지는 대기나 전달 시도를 끝냅니다.

내 쪽 마감 시간은 어떻게 정해야 하나요?

전체 마감 시간은 클라이언트에 둡니다. 이것은 30초를 절대 넘지 않는 wait_timeout_seconds가 아닙니다. 이 상한은 영상 생성 API 동기 vs 비동기에서 설명합니다.

• 생성 Job: 문서는 영상에 20분 정도가 적당하다고 봅니다. POST /v1/videos에서 생성은 모델과 파라미터에 따라 보통 30초에서 몇 분까지 걸립니다.
• Format 실행: 롱폼 영상은 15분에서 30분짜리 작업입니다. 상한을 임의로 만들지 말고 영수증의 expires_at을 쓰세요. 실행이 종료되면 이 값은 null입니다.
• terminal이 true가 되거나 애플리케이션에서 정한 마감 시간이 지날 때까지 폴링하되, 읽기 사이에는 next_poll_after_seconds를 따르세요.

SDK 타임아웃은 어떻게 동작하나요?

세 헬퍼 모두 기본적으로 2초마다 폴링합니다. waitForJob에서는 이 간격이 하한이며, next_poll_after_seconds가 간격을 더 늘릴 수 있습니다. 문서에 따르면 영상 Format은 보통 10–20분 걸립니다. waitForRun은 대기 후가 아니라 대기 전에 마감 시간을 확인하며, signal은 어느 대기든 진행 중인 요청과 함께 중단합니다. 헬퍼 전체는 Sume SDK에서 기다리기에서 다룹니다.

일시적인 읽기 실패가 곧바로 대기를 끝내지는 않습니다. createSumeClient는 408, 429, 5xx와 전송 실패를 지수 백오프와 지터를 두고 retry-after를 따라 두 번 재시도하며, waitForRun은 연속된 일시적 읽기 실패를 6번까지 견딥니다. 롱폼 영상이라면 타임아웃을 늘리세요.

import { SumeRunTimeoutError, waitForRun } from "@sume-com/sdk";

try {
  const run = await waitForRun(runId, {
    client,
    family: "format",
    timeout: 45 * 60_000, // raise the 10-minute default for long-form video
  });
} catch (error) {
  if (error instanceof SumeRunTimeoutError) {
    // The run is still going. Nothing was lost — read it later from `result_url`.
    await markPending(error.runId, error.lastStatus);
  } else {
    throw error;
  }
}

Sume가 Job이나 실행을 스스로 끝내는 것은 언제인가요?

Format 실행은 표에 나온 expires_at 한도에서 failed로 강제 종료됩니다. phase 타임라인에서 마지막 항목의 at이 몇 분 동안 바뀌지 않으면, 그 실행은 느린 것이 아니라 멈춘 것이며 그 한도에서 종료됩니다.

생성 Job이 아직 끝나지 않은 채 시간 한도에 닿은 실행은 incomplete_assembly로 실패하며, details.pending_jobs[]가 그 Job들을 알려 줍니다. previous_run_id로 실행을 이어 가세요. 이미 끝난 클립은 다시 생성되지 않습니다.

생성 Job에는 현재 공개된 큐 만료 옵션이 없습니다. 실패한 Job의 error.category는 generation_timeout이나 worker_timeout일 수 있으며, 문서가 제시하는 두 경우의 일반적인 다음 동작은 상태를 폴링하거나 나중에 재시도하는 것입니다. 이 오류를 읽는 방법은 AI 영상 Job은 왜 실패했나요?에서 보여 줍니다.

내 타임아웃이 발동하면 어떻게 되나요?

Sume 쪽에서는 아무것도 바뀌지 않습니다. Job이나 실행은 계속 실행되고 계속 과금됩니다. 두 번 지불하지 않고 작업을 다시 이어받는 방법은 AI 영상 API 멱등성 키에서 다룹니다. SDK에서는 타임아웃 오류에 이어 가는 데 필요한 정보가 담깁니다. SumeJobTimeoutError에는 jobId가, SumeRunTimeoutError에는 runId와 lastStatus가 있습니다. 나중에 getApiJob이나 getFormatRun으로 작업을 다시 읽거나, 명시적으로 취소하세요.

MCP 타임아웃과 웹훅 타임아웃은 어떻게 다른가요?

호스팅 MCP의 jobs_wait 호출은 아무것도 전송하지 않은 채 열려 있는 HTTP 요청 하나이고, 어떤 엣지든 그런 요청을 결국 끊습니다. 그래서 서버가 슬라이스마다 상한을 둡니다. timeout_seconds의 기본값은 50, 상한은 55이며, 더 큰 값은 거부되지 않고 클램프되고, 응답의 wait_slice_clamped가 그 사실을 알려 줍니다. 십 분짜리 렌더는 대기를 반복해서 기다리세요. 재시도와 배치 대기는 긴 영상 Job을 위한 MCP jobs_wait에서 다룹니다.

Job 웹훅 수신기에는 시도당 10초가 주어지며, 시도 사이에는 고정 지연(기본 30초)이 있습니다. 이벤트를 내구성 있게 저장한 뒤 아무 2xx나 반환하고, 오래 걸리는 작업은 그 뒤에 하세요.