2026-09-26미디어 도구

렌더링 전 영상 타임라인 JSON 검증: Sume plan 사전 검사

POST /v1/timeline-1.0/plan은 Timeline 1.0 문서를 과금 없이 검사하고 길이, 과금 대상 분 수, 비용 추정치, 필터그래프 요약을 반환합니다.

읽는 시간 6분Sume

Sume API로 영상 타임라인을 렌더링하기 전에 검증하려면 같은 JSON 본문을 POST /v1/timeline-1.0/plan으로 보내세요. plan은 스키마, Sume 호스트 URL 검사, 컴파일러를 실행한 뒤 길이, 과금 대상 분 수, 비용 추정치, 필터그래프 요약이 담긴 timeline_plan을 반환합니다. Job을 만들지 않고, 크레딧을 예약하지 않으며, 미디어도 내려받지 않습니다.

아래 내용은 2026-09-26에 확인한 Timeline 1.0 문서와 Sume API 레퍼런스의 plan 항목을 기준으로 합니다. 현재 동작이라고 설명한 내용은 Sume의 코드에서 확인한 것입니다. 렌더 자체는 롱폼 영상을 조립하는 방법에서 다룹니다.

plan은 어떻게 호출하나요?

렌더 본문을 그대로 보내세요. plan은 POST /v1/timeline-1.0/render와 같은 요청 스키마를 받습니다. 다른 경로와 마찬가지로 API 키로 인증하며, Idempotency-Key는 필요 없습니다. 유효한 문서에는 200으로 응답하고, 규칙을 어긴 문서에는 안정적인 오류 코드와 함께 400으로 응답합니다.

curl -X POST https://api.sume.com/v1/timeline-1.0/plan \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio": {
      "url": "https://media.sume.com/artifacts/artf_demo/voice.wav",
      "duration_seconds": 95
    },
    "video": [
      { "source_url": "https://media.sume.com/artifacts/artf_demo/intro.mp4", "start": 0, "duration": 40 },
      {
        "source_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
        "start": 40,
        "duration": 55,
        "transition": { "type": "fade", "duration": 0.25 }
      }
    ]
  }'

plan은 무엇을 반환하나요?

아래 필드는 모두 응답에 반드시 들어갑니다. 위 예시의 95초짜리 스파인이라면 billable_minutes는 2입니다. output.fps를 생략했으므로 현재 코드는 이 plan을 30 fps로 컴파일하며, 이때 0.25초 페이드는 7.5프레임이 되므로 warnings[]에 transition_snapped_to_frame이 담깁니다.

Timeline 1.0과 Sume API 레퍼런스 기준 `timeline_plan` 객체, 2026-09-26 확인.
필드	담기는 값
`object`	`timeline_plan`.
`valid`	불리언. 현재 코드에서는 실패하는 문서에 plan 대신 `400`이 반환됨.
`duration_seconds`	출력 길이, 즉 `audio.duration_seconds`.
`segment_count`	컴파일된 `video[]` 슬롯 수.
`coverage_seconds`	현재 코드에서는 마지막 슬롯이 끝나는 지점, 즉 그 슬롯의 `start`에 `duration`을 더한 값.
`billable_minutes`	현재 코드에서는 `ceil(duration_seconds / 60)`, 최소 1.
`estimated_cost_usd_micros`	비용 추정치. 단위는 US 달러의 백만분의 일.
`transition_count`	그래프에 컴파일된 트랜지션 수.
`filtergraph_summary`	컴파일된 그래프를 요약한 문자열.
`warnings[]`	각 항목에 `code`와 `message`, 선택적으로 `segment_index`와 `context`가 있음.

plan은 무엇을 검사하나요?

스키마와 접수 단계의 범위 검사, 모든 URL에 대한 Sume 호스트 검사, 그리고 컴파일러를 실행합니다. 컴파일러가 검사하는 것은 롱폼 영상을 조립하는 방법에 정리된 프로그램 규칙과 거부 코드로, timeline_must_start_at_zero부터 too_many_chained_transitions까지입니다. 현재 코드에서 plan과 렌더는 같은 검증기를 호출하므로, plan이 반환한 400에는 렌더가 반환했을 코드가 그대로 담깁니다.

plan이 예측하지 못하는 것은 무엇인가요?

plan은 미디어를 내려받지 않으므로, 파일에 따라 달라지는 다음 항목은 렌더링할 때에만 드러납니다.

짧은 소스: 클립보다 긴 슬롯은 패딩되거나 루프되고, 트랜지션에 필요한 분량이 부족한 경계는 하드 컷이 됩니다. 문서는 plan이 이런 경고를 예측할 수 없다고 설명합니다.
출력보다 짧은 사운드트랙(soundtrack_shorter_than_spine): 현재 코드에서 plan은 배경 음악의 길이를 알지 못합니다.
프레임 레이트: output.fps를 생략하면 현재 코드는 plan을 30 fps로 컴파일하지만 렌더는 소스가 쓰는 프레임 레이트를 쓰므로, 트랜지션 스냅 결과가 달라질 수 있습니다. 둘을 맞추려면 output.fps를 지정하세요.
없는 클립: 현재 코드에서 plan은 각 URL의 호스트는 검사하지만 렌더가 각 파일에 보내는 요청은 건너뛰므로, 없는 클립도 plan은 통과하고 렌더에서 source_not_found로 거부됩니다.

추정치는 렌더가 예약하는 금액과 같나요?

정확히 같지는 않습니다. 현재 코드에서 estimated_cost_usd_micros는 billable_minutes에 정가 요율, 즉 API 요금의 출력 분당 $0.10를 적용한 값이며 에이전트 수수료는 들어가지 않습니다. 렌더는 ceil(audio.duration_seconds / 60)분을 같은 요율로 예약하고, 여기에 기본적으로 5.5% 에이전트 수수료가 더해집니다. 문서는 GET /v1/catalog에서 요율을 실시간으로 확인하라고 안내합니다.

plan은 잔액도 확인하지 않습니다. 잔액 부족으로 402를 반환할 수 있는 것은 렌더뿐입니다. 비용을 쓰기 전에 가격을 확인하는 다른 방법은 AI 영상 비용을 추정하는 방법을 참고하세요.

파이프라인에서 plan은 어떻게 쓰나요?

문서를 만드는 단계와 비용을 지불하는 단계 사이에 들어가는, 과금되지 않는 컴파일 단계로 다루세요.

문서를 만들고 plan을 호출합니다.
400을 받으면 오류가 가리키는 필드를 고치고 다시 plan을 호출합니다. 과금된 것은 없습니다.
duration_seconds, coverage_seconds, billable_minutes가 의도한 렌더와 맞는지 확인하고 warnings[]를 읽습니다. 스냅된 트랜지션과 무시된 스틸 모션은 실패가 아닌 소프트 경고입니다.
Idempotency-Key와 함께 렌더링한 뒤, plan이 볼 수 없는 파일 의존적인 경우는 결과의 warnings[]에서 확인합니다.

출처

작성자 Sume