API로 영상 요약하기: 전사문, 스틸, 그리고 JSON

Sume API로 영상을 요약하려면 클립에 transcribe: true를 넣어 POST /v1/video-inspect를 실행하고, 시각이 표시된 스틸과 전사문을 받으세요. 그런 다음 스틸은 input_image 첨부로, 전사문은 input에 담아 POST /v1/agent/completions로 보내고, 요약과 챕터를 JSON으로 만드는 output_schema를 함께 지정하세요.

아래 내용은 2026-09-27에 확인한 Sume 문서 영상 검사와 Agent Completions 페이지, 두 페이지가 함께 따르는 구조화 출력 (영문) 규칙, Sume API 레퍼런스의 검사 결과 스키마에서 가져왔습니다. 두 단계는 각각 별도 글에서 다룹니다. 영상 검사 API와 이미지 입력·JSON 출력 에이전트 API를 참고하세요.

왜 영상 파일 대신 스틸과 전사문을 보내나요?

Agent Completions는 영상이 아니라 이미지를 첨부합니다. 현재 첨부 타입은 input_image뿐입니다. 그래서 이 방법은 검사가 클립에서 뽑아낸 것, 즉 시각을 알고 있는 스틸과 말한 단어를 에이전트에게 넘깁니다.

검사는 앞서 실행한 Sume Job의 출력처럼 이미 워크스페이스의 media.sume.com에 있는 클립 하나를 읽으며, 길이는 최대 1,800초입니다. 공개 인터넷에서 가져오는 기능은 없으므로, 호스트 밖 URL은 접수 단계에서 거부됩니다.

스틸과 전사문은 어떻게 뽑나요?

클립의 video_url과 Idempotency-Key를 담아 POST /v1/video-inspect를 보내세요. 기본 sync 모드는 최대 30초 기다린 뒤 완료된 검사를 200으로 돌려주거나, Job을 202로 돌려줍니다. 나중에 GET /v1/video-inspect/:id로 조회하세요.

• frames: 생략하면 구간 중간(mid-bin) 스틸 8장을 받고, { "fps": n }(0 초과, 최대 2)을 보내면 1/n초마다 스틸을 한 장씩 받습니다. 호출 하나는 스틸을 최대 24장 반환하며, 각 스틸은 media.sume.com에 있는 { t, url, width, height }입니다.
• 현재 코드에서 fps 프로그램은 처음 24장만 남기므로, n은 클립 길이에 맞춰 정하세요. 아래 예시의 fps: 0.02는 20분짜리 클립에 걸쳐 50초 간격으로 스틸 24장을 배치합니다.
• transcribe: true는 text와 words[]가 담긴 transcript를 추가합니다. segmentation: { "mode": "sentence" }를 주면 갭 없는 문장 segments[]도 반환하며, 각 세그먼트에는 index, text, start, end, duration_seconds가 담깁니다.
• 오디오 트랙이 없는 클립은 inspect_source_has_no_audio로 실패합니다. 먼저 probe.has_audio를 확인하려면 frames: false 검사로 충분하며, 이 검사의 프로브는 duration_seconds도 알려 줍니다.

curl -X POST https://api.sume.com/v1/video-inspect \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webinar-inspect-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/webinar.mp4",
    "frames": { "fps": 0.02 },
    "transcribe": true,
    "segmentation": { "mode": "sentence" }
  }'

요약을 JSON으로 받으려면 어떻게 하나요?

agent_completions:write가 있는 키로 스틸과 전사문을 POST /v1/agent/completions에 보내세요.

• attachments: 각 스틸을 input_image로 넣으며, 실행당 최대 30장입니다. 이미 media.sume.com에 있는 URL은 다시 복사하지 않습니다. filename은 에이전트가 보는 라벨이므로 스틸의 시각을 넣으세요.
• input: 전사문의 segments를 넣습니다. input은 통째로 파일에 기록되며, 지시로는 절대 다뤄지지 않고 데이터로만 다뤄집니다.
• output_schema: 요약과 챕터의 형태를 엄격한 부분집합 안에서 정의합니다. 모든 객체가 additionalProperties: false를 설정하고, 모든 속성이 required에 나열됩니다.
• generation_spend_cap_usd: 필수이며 기본값이 없습니다. 생략하면 요청이 400 invalid_request로 실패합니다.

curl -sS -X POST "https://api.sume.com/v1/agent/completions" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webinar-summary-v1" \
  -d '{
    "instruction": "Summarize the video from the attached stills and the transcript in input. List chapters with start times.",
    "input": { "segments": [{ "text": "Welcome to the demo.", "start": 0, "end": 2.4 }] },
    "attachments": [
      { "type": "input_image", "image_url": "https://media.sume.com/artifacts/artf_demo/still-1.jpg", "filename": "t-25s.jpg" }
    ],
    "output_schema": {
      "name": "acme/video-summary/v1",
      "schema": {
        "type": "object", "additionalProperties": false,
        "required": ["summary", "chapters"],
        "properties": {
          "summary": { "type": "string" },
          "chapters": { "type": "array", "items": { "$ref": "#/$defs/chapter" } }
        },
        "$defs": { "chapter": { "type": "object", "additionalProperties": false, "required": ["title", "start_seconds"],
          "properties": { "title": { "type": "string" }, "start_seconds": { "type": "number" } } } }
      }
    },
    "generation_spend_cap_usd": 2
  }'

결과는 어떻게 읽나요?

이미지 입력·JSON 출력 에이전트 API에서처럼 agent.run 영수증을 폴링하거나 agent.run.terminal 웹훅을 받으세요. 완료된 실행은 여러분의 스키마대로 output을 채웁니다. 실행이 만든 것 중 스키마를 만족하는 것이 없으면 output은 null이고 output_error가 이유를 알려 주며, API에서는 실행이 failed로 끝납니다.

스키마가 고정하는 것은 형태이지 사실이 아닙니다. 문서에 따르면 URL과 길이를 제외한 값은 실행이 자기 작업을 스스로 설명한 것이며, 검증된 측정값이 아닙니다. input은 데이터로 다뤄지므로 전사문은 instruction이 아니라 input에 두세요. 이 경계가 무엇을 막고 무엇을 막지 못하는지는 AI 에이전트에 고객 데이터를 안전하게 넘기는 방법에서 다룹니다.

제한은 무엇이고, 비용은 얼마인가요?

프로브와 스틸은 과금되지 않으며, 예약이 걸리는 것은 전사뿐입니다. 전사는 API 요금에 나온 STT 1.0 공개 요율인 오디오 분당 $0.01로 예약됩니다. completion의 비용은 에이전트 자체의 턴을 포함해 GET /v1/usage?run_id=가 돌려주는 debited_usd_micros입니다.