장면 원장으로 실패한 AI 영상 실행의 부분 결과 받기

실패한 Sume Format 실행도 자기가 만든 부분 결과를 output에 싣습니다. 단, 출력 스키마가 부분 결과를 적법한 형태로 인정할 때만 그렇습니다. 선택 필드는 nullable로 만들고, 장면 목록에는 minItems를 두지 말고, 완성 영상을 primary_output_key로 지정하세요. 그러면 반쯤 만들어진 영상도 렌더링한 장면을 보고할 수 있고, 실행은 여전히 failed로 돌아옵니다.

아래 규칙은 2026-09-26에 확인한 Sume 문서 구조화 출력 (영문)과 오류와 비용 (영문) 페이지에서 가져왔습니다. 스키마를 처음 바인딩하는 방법은 Sume Format 구조화 출력에서 다룹니다.

실패한 실행도 무엇을 돌려주나요?

오류 이상을 돌려줍니다. output은 실행이 실패했다는 이유만으로 null이 되는 것이 아니라, 스키마를 충족한 것이 하나도 없을 때만 null입니다. 문서의 예는 장면 40개 중 20개를 렌더링하고 멈춘 방송입니다. 이 실행은 그 20개를 output에 보고하고, 나머지 장면에는 여러분의 스키마가 정의한 “failed” 값이 들어가며, output_error가 멈춘 이유를 설명합니다.

• artifacts[]는 어느 경우든 실행이 만든 모든 것으로 채워집니다.
• primary_output_key와 primary_output_url은 완료되지 않은 모든 실행에서 null이므로, 부분 결과가 완성본으로 통과할 수는 없습니다.
• API에서는 스키마에 맞지 않는 결과가 곧 실행 실패입니다. status는 failed가 되고, error에는 output_error와 같은 이유가 담깁니다.

스키마가 부분 결과를 허용하게 하려면 어떻게 하나요?

Sume는 자체 하한을 따로 두지 않습니다. 검증기는 여러분이 쓴 키워드를 정확히 그대로 강제하므로, 모든 장면을 요구하는 스키마는 40개 중 20개를 만든 방송을 다시 output: null로 되돌립니다. 두 가지 규칙이 이 일을 합니다.

• 선택 사항은 빠져도 된다는 뜻이 아니라 nullable이라는 뜻입니다. 모든 속성은 여전히 required에 나열되어야 하며, “may not exist”(없을 수도 있음)는 "type": ["string", "null"]로 표현하세요.
• 일부만이라도 받고 싶은 배열에는 minItems를 두지 마세요. minItems는 강제되므로, 장면 목록에 minItems: 1을 두면 읽으려던 바로 그 원장이 거부됩니다.

장면 원장 스키마는 어떻게 생겼나요?

아래는 문서의 원장 스키마에서 description 주석을 뺀 것입니다. 네임스페이스를 둔 name, strict: true와 함께 output_schema 안의 schema로 바인딩하고, 같은 실행에 "primary_output_key": "full_video"를 보내세요.

{
  "type": "object",
  "additionalProperties": false,
  "required": ["full_video", "scenes", "notes"],
  "properties": {
    "full_video": { "type": ["string", "null"] },
    "scenes": { "type": "array", "items": { "$ref": "#/$defs/scene" } },
    "notes": { "type": ["string", "null"] }
  },
  "$defs": {
    "scene": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "status", "video_url", "failure_reason"],
      "properties": {
        "id": { "type": "string" },
        "status": { "type": "string", "enum": ["completed", "failed", "skipped"] },
        "video_url": { "type": ["string", "null"] },
        "failure_reason": { "type": ["string", "null"] }
      }
    }
  }
}

원장을 왜 primary_output_key와 함께 쓰나요?

느슨해진 스키마를 정직하게 지켜 주기 때문입니다. scenes는 채웠지만 full_video를 null로 둔 실행은 스키마는 충족했어도 완성본을 만들지 못했으므로, 성공을 보고하는 대신 primary_output_missing과 함께 failed로 끝납니다. 문서의 표현을 빌리면, 느슨함으로 얻는 것은 부분 결과에 대한 가시성이지 실행의 통과가 아닙니다.

부분 결과는 어떻게 읽나요?

output을 읽기 전에 output_error를 확인하고, output이 null이면 artifacts[]로 폴백하세요. 그런 다음 “did I get a show”(방송을 받았는가)는 full_video로, “what do I need to retry”(무엇을 재시도해야 하는가)는 각 scenes[].status로 분기하세요. 문서는 세 가지 실패 코드에서 output에 부분 결과가 실린다고 설명합니다.

• primary_output_missing: 결과는 스키마를 충족했지만, primary_output_key로 지정한 키가 비어 있습니다.
• agent_reported_failure: 실행 스스로 결과를 전달하지 못했다고 보고했으며, output에는 만들어진 것의 원장이 실립니다.
• incomplete_assembly: 생성 Job이 아직 끝나지 않은 채 실행이 시간 한도에 도달했으며, 스키마가 허용하면 부분 원장이 output에 실립니다.

빠진 장면만 어떻게 재시도하나요?

실패한 실행의 ID를 새 실행의 previous_run_id로 보내고, 다시 만들 장면을 지정하세요. 쿡북의 레시피는 장면 하나를 input.scene_id에서, 두 장면을 한 번에 할 때는 scene_ids에서 읽습니다. 다음 턴은 끝난 클립이 이미 담긴 같은 대화를 이어받습니다. 호출 방법, 거부 응답, 예산은 AI 영상의 장면 하나를 다시 생성하기에서 차례로 설명합니다.

쿡북에 있는 이 스키마의 변형은 각 클립의 타입을 SumeMediaFile#로 지정하고, status 값으로 succeeded, stand-in, failed를 씁니다. 거기서는 stand-in이나 failed로 표시된 장면이 장면 재시도 레시피가 고치는 대상입니다.