AI 영상 배치 실패 항목 재시도: Sume 대량 실행 복구

Sume 대량 실행 배치에서 실패한 항목을 재시도하려면, 큐의 status가 completed가 될 때까지 기다렸다가 counts.failed와 counts.canceled를 읽고 실패한 항목을 유형별로 처리하세요. 결과물을 남긴 자식 실행은 previous_run_id로 이어 가고, 나머지는 새 Idempotency-Key를 붙여 새 실행으로 다시 제출합니다.

아래 단계는 2026-09-26에 확인한 Sume 문서 대량 실행, 실행과 결과 (영문), 오류와 비용 (영문) 페이지에서 가져왔습니다. 큐를 만들고 끝까지 처리하는 과정은 Sume Format 대량 실행에서 다룹니다.

배치에서 실패한 항목은 어떻게 찾나요?

큐 status가 completed가 될 때까지 GET /v1/format-run-queues/{queue_id}를 폴링하세요. 이 상태는 모두 성공했다는 뜻이 아니라 모든 항목이 종료됐다는 뜻이며, 이때 finished_at도 설정됩니다. 그다음 counts.failed와 counts.canceled로 분기하세요.

items의 각 행에는 index, status, run_id, error가 들어 있습니다. index는 제출한 배열에서 영부터 센 위치이므로, 원본 데이터의 행과 인덱스를 잇는 매핑은 직접 보관하세요. 아래 필터는 복구할 행을 나열합니다.

curl -sS "https://api.sume.com/v1/format-run-queues/$QUEUE_ID" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  | jq -c '.data.items[] | select(.status == "failed" or .status == "canceled")
      | {index, status, run_id, code: .error.code}'

각 항목은 어떤 종류의 실패인가요?

항목의 status와 run_id를 보면 세 가지 경우 중 어디에 속하는지 알 수 있습니다. 자식 실행이 끝나면 항목의 error에는 일반적인 값만 담기므로, 실제 이유는 GET /v1/format-runs/{run_id}에서 자식 실행 자체의 영수증을 읽어 확인하세요.

실패한 자식 실행은 이어 가야 하나요, 다시 시작해야 하나요?

실패가 클립을 남겼다면 이어 가세요. 영수증에 null이 아닌 thread_id가 있고, 상태가 completed이거나 artifacts[]가 비어 있지 않으면 그 실행은 이어 갈 수 있습니다. 같은 Format의 새 실행에 그 실행의 ID를 previous_run_id로 보내고(스레드 ID는 절대 보내지 마세요), 같은 output_schema를 다시 바인딩하세요. 스키마는 실행마다 따로이며 물려받지 않습니다. 아무것도 남기지 않은 실행은 400 previous_run_not_resumable로 거부되므로, 그 행은 새로 시작하세요.

자식 실행의 error.code를 보면 선택지가 좁혀집니다. 이 코드 집합은 열려 있으므로, 모르는 코드는 그대로 통과시키세요.

• incomplete_assembly: previous_run_id로 이어 가세요. 끝난 클립은 스레드에 있고 다시 생성되지 않습니다.
• primary_output_missing: 실행을 이어 가서 빈 곳을 채우거나 재시도하세요.
• unattended_blocked: 입력이나 브리프를 고친 뒤 새 Idempotency-Key로 재시도하세요.
• output_schema_unsatisfied: 대개 Format이 만들지 않는 파일을 요구하는 스키마가 원인입니다. 먼저 스키마를 nullable로 풀거나 지시문을 바꾸세요.
• provider_unavailable 또는 mcp_unavailable: 새 Idempotency-Key로 재시도하세요.
• format_run_failed: 일반 코드입니다. 상한을 넘어 쓰려던 실행도 여기로 오므로 usage.billable_amount_usd_micros와 usage.generation_spend_cap_usd_micros를 비교하세요.

실패한 행만 다시 제출하려면 어떻게 하나요?

실패한 행만으로 새 대량 실행 요청을 만드세요. 각 항목은 단일 POST …/runs와 같은 본문이므로, 이어 갈 수 있는 행은 previous_run_id를 담고, 새로 시작하는 행은 원래의 instruction과 input을 담으며, 항목마다 자체 generation_spend_cap_usd를 둘 수 있습니다.

새 Idempotency-Key를 보내세요. 첫 배치의 키에 같은 { concurrency, items }를 보내면 202와 함께 예전 큐가 돌아오고, 다른 페이로드를 보내면 409 idempotency_conflict입니다. 행이 몇 개뿐이라면 단일 실행으로 보내도 됩니다. 각 키는 행과, 의도적으로 다시 실행할 때 올리는 버전에서 유도하세요. 같은 키에 같은 본문을 보내면 두 번째 실행이 시작되지 않고 idempotency_hit: true가 담긴 원래 영수증이 돌아옵니다.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/bulk-runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: spring-catalog-batch-1-retry-1" \
  -d '{
    "concurrency": 2,
    "items": [
      { "previous_run_id": "arun_…", "instruction": "Redo the failed part only. Keep the rest unchanged." },
      { "instruction": "clip 4", "input": { "url": "https://example.com/4.jpg" } }
    ]
  }'

재시도 비용은 어떻게 되나요?

이어 가기는 새 실행입니다. ID와 영수증이 새로 생기고, 지출 상한도 따로 갖고, 웹훅도 따로 한 번 보냅니다. 에이전트에게는 앞서 만든 결과가 다시 주어지므로, 한 부분만 다시 하고 나머지는 그대로 둘 수 있습니다. usage는 실행별로 따로 집계됩니다.

실패 전에 끝난 생성은 과금되며, 이후 단계가 실패해도 환불되지 않습니다. 생성 시점의 4xx와 멱등 200 재전송은 비용이 들지 않습니다. mcp_unavailable이면 생성이 실행되지 않았고 과금된 것도 없습니다.

대량 실행 API는 재시도와 관련해 무엇을 해 주지 않나요?

failed나 canceled 항목은 종료 상태입니다. 슬롯을 비우고 나머지 큐는 계속 진행되므로, 복구는 여러분의 코드가 맡아야 합니다. 큐 웹훅이 없고 큐 목록·큐 취소 엔드포인트도 없다는 점을 비롯한 큐의 일반적인 제약은 Sume Format 대량 실행에서 다룹니다. 재시도에는 다음 세 가지 규칙이 적용됩니다.

• 콜백을 받으려면 재시도 항목마다 communication.webhook_url을 따로 넣어야 합니다. 취소되거나 건너뛴 실행은 웹훅을 보내지 않습니다.
• 이어 가기는 원래 실행을 절대 바꾸지 않으므로, 여러분 쪽 행이 새 실행 ID를 가리키도록 바꾸세요.
• 재시도한 자식 실행도 모두 지갑, 워크스페이스 생성 동시성, 지출 상한 접수 검사를 그대로 거칩니다. insufficient_credits 뒤에는 먼저 충전하세요. 충전하지 않고 재시도하면 같은 답이 돌아옵니다.