Sume API로 AI 영상의 장면 하나를 다시 생성하기

Sume Format으로 만든 AI 영상에서 장면 하나를 다시 생성하려면, 이전 실행의 ID를 previous_run_id로 담아 POST /v1/formats/{handle}/{slug}/runs를 새로 보내고 그 장면을 지정하세요. 다음 에이전트 턴이 같은 대화를 이어 가므로, 그 클립만 다시 만들고 나머지는 그대로 둘 수 있습니다. 쿡북의 장면 재시도 레시피에서는 음성 트랙, 다른 클립, 대본이 그대로 유지되고, 전체 장면 목록이 다시 조립되어 돌아옵니다.

아래의 절차, 거부 응답, 예산 조언은 2026-09-26에 확인한 Sume 문서 실행과 결과 (영문), 쿡북, 오류와 비용 (영문) 페이지에서 가져왔습니다.

장면 하나는 어떻게 재시도하나요?

첫 실행부터 대비해 두세요. scenes[]가 모든 클립에 안정적인 id를 부여하는 output_schema를 바인딩하고, 202 응답의 data.id와 data.thread_id를 저장하세요. 앞의 것은 영수증용이고, 뒤의 것은 재시도를 묶는 용도입니다. 장면 원장 스키마의 예는 실패한 AI 영상 실행의 부분 결과에 있습니다.

그런 다음 쿡북의 예와 같은 본문으로 그 실행을 이어 가세요.

• previous_run_id: 이어 갈 실행입니다.
• instruction: 운영자의 메모입니다. 어느 장면인지, 무엇이 잘못됐는지, 어떻게 바뀌어야 하는지 적으세요.
• input: 기계가 읽는 포인터입니다. input에는 고정된 필드가 없으므로 레시피가 읽는 키를 쓰세요. 쿡북은 scene_id를 보내고, 두 장면을 한 번에 다시 만들 때는 "scene_ids": ["sc_7", "sc_9"]를 보냅니다.
• output_schema: 첫 실행에 바인딩한 것과 같은 스키마입니다. 스키마는 실행마다 따로 적용되며 상속되지 않습니다.
• generation_spend_cap_usd와, 이번 재시도를 위한 새 Idempotency-Key입니다.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8823-v1-retry-sc_7" \
  -d '{
    "previous_run_id": "arun_123",
    "instruction": "Retry the selected scene only. Keep every other scene and the voice track unchanged. Do not change the script. New take only.",
    "input": { "scene_id": "sc_7" },
    "output_schema": { "…": "identical to the first run" },
    "primary_output_key": "full_video",
    "generation_spend_cap_usd": 8,
    "communication": { "webhook_url": "https://acme.example.com/hooks/sume" }
  }'

어떤 실행을 이어 갈 수 있나요?

이전 실행의 영수증에서 바로 확인할 수 있습니다. thread_id가 null이 아니고, 실행이 completed로 끝났거나 artifacts[]가 비어 있지 않으면 이어 갈 수 있습니다. 그래서 작업을 남긴 failed 실행은 이어 갈 수 있고, 아무것도 남기지 않은 실행은 이어 갈 수 없습니다. API가 받아들일 수 없는 이어 가기 요청은 생성 시점에 거부되며, 이때는 아무것도 실행되지 않고 아무것도 청구되지 않습니다.

장면 재시도에서는 무엇이 돌아오나요?

이어 가기는 새 실행입니다. 새 arun_… ID와 새 영수증이 생기고, 지출 상한도 따로 가지며, format.run.terminal 웹훅도 따로 한 번 발송됩니다. 원래 실행은 절대 바뀌지 않고, 그 웹훅도 다시 발송되지 않습니다. 두 실행은 읽기 전용인 같은 thread_id를 공유하며, 새 영수증의 previous_run_id가 이어 간 실행을 가리킵니다. 전달은 Sume Format 실행 수명주기에서 설명한 대로 동작합니다.

쿡북의 장면 스키마를 쓰면 새 영수증은 다음과 같이 읽힙니다.

• output.scenes[]는 다시 전체 목록입니다. 재시도한 장면은 새 URL을 받고, 나머지 장면은 기존 URL을 유지합니다.
• full_video는 새 URL로 다시 조립됩니다.
• artifacts[]에는 대화 전체가 생성한 모든 것이 나열되지만, usage는 실행별로 유지됩니다.

장면 재시도에는 비용이 얼마나 드나요?

쿡북은 장면 하나 재시도의 예산을 처음 생성 비용의 일부로 잡으라고 합니다. 측정된 프로덕션 재시도는 첫 실행 지출의 약 이십분의 일이었습니다. 오류와 비용 페이지에 따르면 프로덕션의 긴 영상 실행은 보통 $120 안팎의 상한으로 만들고, 장면 하나 재시도는 몇 달러 상한으로 만듭니다. 위의 쿡북 재시도 예시는 $8 상한을 보냅니다. 상한은 항상 보내세요.

상한은 generation_spend_cap_usd로 보내며, 플랫폼 최대치인 $500까지 지정할 수 있습니다. 생략하면 재시도는 Format의 상한을 물려받습니다. 재시도의 usage.billable_amount_usd_micros는 그 상한에 대해 집계되는 생성 지출이며, API 요금에 나온 요율로 계량됩니다. 에이전트 자체의 LLM 턴은 여기에 포함되지 않으므로, 지갑에서 실제로 차감된 금액은 usage.debited_usd_micros에서 읽으세요.

실패한 실행은 이어 가야 하나요, 새로 시작해야 하나요?

실패가 클립을 남겼다면 문서는 새 실행 대신 그 실행을 이어 가는 쪽을 권합니다. 다음 실패 코드들이 그런 경우입니다.

• incomplete_assembly: 생성 Job이 끝나지 않은 채 실행이 시간 한도에 도달했습니다. previous_run_id로 이어 가세요. 끝난 클립은 스레드에 있으며 다시 생성되지 않습니다.
• primary_output_missing: 결과는 스키마를 충족했지만, 지정한 primary_output_key가 비어 있습니다. 실행을 이어 가서 빈 곳을 채우거나 재시도하세요.
• agent_reported_failure: 실행 스스로 결과를 전달하지 못했다고 보고했습니다. 예를 들어 미디어 슬롯이 failed나 stand-in으로 표시된 경우입니다. output에 있는 클립은 실제 결과이며 재시도해도 다시 생성되지 않습니다. 실행을 이어 가거나 새 Idempotency-Key로 다시 실행하세요.

장면 재시도가 맞지 않는 경우는 언제인가요?

재시도는 재인코딩이 아니라 새 테이크입니다. 그 장면의 생성 요소는 전부 새로 생성됩니다. 쿡북이 제시하는 경험칙은 다음과 같습니다.

• 보이는 모습이 잘못됐다면: 장면을 재시도하세요.
• 문구, 호스트, 제품이 바뀐다면: 새 장면 ID로 새 제작을 시작하세요.
• 새 실행에는 새 Idempotency-Key가 필요합니다. 이전 키는 이미 받은 영수증에 묶여 있기 때문입니다. 언제 재시도하고 언제 이어 갈지는 Sume Format 실행 실패 코드에 정리되어 있습니다.