영상 에이전트 API: 브리프 하나로 편집된 완성 영상 받기

네. 영상 에이전트 API는 평범한 말로 쓴 브리프를 받아 완성된 영상을 돌려줍니다. 에이전트가 샷을 계획하고, 생성 모델을 호출하고, 조각들을 파일 하나로 편집하므로 타임라인을 직접 쓸 필요가 없습니다. Sume는 이런 호출을 두 가지 문서화합니다. 일회성 브리프에는 Agent Completions(POST /v1/agent/completions)를, 새 입력으로 호출하는 저장된 레시피에는 Format(POST /v1/formats/{handle}/{slug}/runs)을 씁니다. HeyGen도 Video Agent 엔드포인트를 문서화합니다.

Sume에 관한 사실은 Agent Completions, Format API (영문), Sume 기초 문서에서, 다른 공급사에 관한 사실은 각 공급사의 개발자 문서에서 가져왔습니다. 모두 2026-09-28에 확인했습니다. 아래에서는 이 문서들에서 "완성·편집된" 영상이 무엇을 뜻하는지, 에이전트 API가 모델 API나 렌더 API와 어떻게 다른지, 최소 요청의 모습, 그리고 한도를 다룹니다.

여기서 "완성·편집된" 영상은 무슨 뜻인가요?

Sume의 기초 페이지에 따르면 파트너의 주 경로는 개별 생성 도구를 조합하는 샌드박스 Agent나 Format이며, 그렇게 해서 클립 하나로는 낼 수 없는 결과물을 내놓습니다: "multi-minute host footage, B-roll, voiceover, and timeline assembly into a post-ready video."(수 분짜리 호스트 영상, B-roll, 보이스오버, 타임라인 조립까지 거친 게시 준비 영상) Format API (영문)의 실행 다이어그램도 같은 작업을 나열합니다. 호스트 테이크, B-roll, 보이스오버, 자막, 타임라인 조립입니다. 돌아오는 것은 다음과 같습니다.

• 결과물 하나. 완료된 Format 실행에는 문서가 보여 줄 단 하나라고 부르는 primary_output_url과, 실행이 만든 모든 파일인 artifacts[]가 담깁니다.
• output 안의 미디어. 완료된 Agent Completion은 에이전트의 마지막 텍스트를 output.text에, 생성한 미디어를 output.videos, output.images, output.audio, output.files에 담습니다.
• 오래 유지되는 파일. 미디어 URL은 저장해 둘 수 있는 영구 media.sume.com HTTPS URL입니다.
• 전부 아니면 전무. Format 실행은 일부만 전달하는 일이 없습니다. 끝내지 못한 실행은 failed로 돌아오고, 그 primary_output_url은 null입니다.
• 부가 요소는 요청할 때만. 문서의 예시 지시문은 부가 요소를 이름으로 끕니다("No BGM, no captions"). 그러니 보이스오버, 자막, 음악을 원하는지 브리프에 적으세요.

에이전트 API는 모델 API나 렌더 API와 무엇이 다른가요?

직접 쓰는 양이 다릅니다. 모델 API는 프롬프트 하나로 클립 하나를 만듭니다. 렌더 API는 이미 있는 클립을 여러분이 쓴 타임라인에 따라 편집합니다. 아바타 API는 대본을 말하는 클립으로 바꿉니다. 에이전트 API는 브리프를 받아 계획, 생성, 편집을 스스로 합니다. Sume에는 방식마다 엔드포인트가 있습니다.

최소 요청은 어떻게 생겼나요?

브리프를 instruction으로 보내고 generation_spend_cap_usd를 함께 보내세요. 이 필드는 필수이며 기본값이 없습니다. 호출은 agent.run 영수증과 함께 202로 응답합니다. 결과는 웹훅으로 받거나, next_action이 더 이상 poll_status가 아닐 때까지 폴링하세요.

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: teaser-123-v1" \
  -d '{
    "instruction": "Make a 15-second vertical 9:16 promo for https://shop.example.com/p/123 with voiceover and captions. Deliver one MP4.",
    "generation_spend_cap_usd": 10,
    "communication": { "webhook_url": "https://example.com/hooks/sume" }
  }'

# Poll the run until next_action is no longer poll_status
curl -sS "https://api.sume.com/v1/agent-runs/$RUN_ID" \
  -H "Authorization: Bearer $SUME_API_KEY"

Agent Completions와 Format 중 무엇을 써야 하나요?

Sume 문서의 기준은 이렇습니다. 작업 자체가 호출마다 달라지면 Agent Completions를, 저장된 워크플로가 있고 입력만 바뀌면 Format을 쓰세요. 둘 다 같은 에이전트를 실행하고 같은 형태의 영수증을 반환합니다.

백엔드에서 Sume 영상 에이전트 실행하기는 Agent Completions의 모든 필드를 다룹니다. Sume Format이란?은 레시피를 저장하고 호출하는 방법을 다룹니다. 영상 에이전트란?은 용어를 정의하고, AI로 광고 영상 만드는 법은 사람이 먼저 초안을 승인하는 채팅 경로를 따라갑니다.

영상 에이전트 API를 문서화한 다른 공급사는 어디인가요?

이 질문의 답에는 HeyGen, Runway, Synthesia가 자주 나옵니다. 2026-09-28에 각 공급사의 개발자 문서에 적힌 내용은 다음과 같습니다.

• HeyGen: Prompt to Video 문서는 POST /v3/video-agents를 설명합니다. 1–10,000자의 prompt를 보내면 "the agent handles scripting, avatar selection, scene composition, and rendering."(에이전트가 대본 작성, 아바타 선택, 장면 구성, 렌더링을 처리)라고 합니다. 호출은 session_id를 반환하고, 완성된 영상에는 video_url이 담기며, 응답 필드에는 captioned_video_url과 subtitle_url이 있습니다. Sume vs HeyGen에서 두 제품을 비교합니다.
• Synthesia: Create a video 엔드포인트는 input을 받습니다. 이는 "an array of objects that each describe a clip of a multi-clip video,"(여러 클립으로 된 영상의 클립 하나씩을 설명하는 객체 배열)이며, 각 객체는 avatar를 지정하고 대본은 scriptText나 업로드한 scriptAudio로 넣습니다. 위 표의 아바타 행처럼 장면마다 대본을 직접 씁니다.
• Runway: 개발자 문서 색인에 따르면 Runway Dev는 "exposes generative video, image, and audio models over HTTP"(생성형 영상, 이미지, 오디오 모델을 HTTP로 제공)하며, 대부분의 생성 엔드포인트는 폴링할 작업 ID를 반환합니다. 같은 색인에는 Recipes, 곧 "prebuilt multi-step video and image workflows such as product ads and ad localization."(제품 광고와 광고 현지화 같은 미리 만들어 둔 다단계 영상·이미지 워크플로)도 나옵니다.

한도는 무엇인가요?

Agent Completions, 실행과 결과 (영문), 오류와 비용 (영문) 페이지가 정한 한도는 다음과 같습니다.

• 모든 실행에 지출 상한. Agent Completions의 generation_spend_cap_usd에는 기본값이 없으며, 빠뜨리면 400 invalid_request입니다. Format 실행의 상한은 플랫폼 최대치인 $500까지 올릴 수 있습니다. 상한을 지정하지 않은 실행은 Format의 상한을 이어받으며, Format이 상한을 정한 적이 없다면 $400입니다.
• 초가 아니라 분 단위. 영상을 만드는 Format 실행은 몇 분이 걸리며, 문서에 따르면 긴 호스트 영상은 보통 15–30분 안에 끝납니다. created_at에서 90분이 지나도 진행 중인 Format 실행은 failed로 강제 종료되며, 생성된 지 25분이 넘었고 10분 동안 신호가 없으면 더 일찍 종료됩니다.
• 사람이 개입하지 않음. Format 실행은 멈춰서 누구에게 묻지 않습니다. 브리프에 맞는 아바타가 없는 경우처럼 사람 없이는 넘을 수 없는 관문을 만나면 unattended_blocked로 실패합니다.
• 채팅 스트림이 아님. Agent Completions는 choices[]가 아니라 실행 영수증을 반환합니다. 스트리밍, 이전 스레드 이어 가기, 이미지가 아닌 첨부는 아직 지원하지 않으며, 이미지는 최대 30개까지 함께 보낼 수 있습니다.
• 사용한 만큼 과금. 생성에는 API 요금의 요율이 적용되고 기본적으로 5.5% 에이전트 수수료가 더해지며, 영수증의 usage에 실행이 쓴 금액이 기록됩니다.