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

네. 여러 API가 평범한 말로 쓴 브리프를 받아 편집까지 끝난 완성 영상 파일 하나를 돌려줍니다. 서비스가 장면을 계획하고 영상을 생성하거나 조립하며, 일부는 대본까지 쓰고 음성, 자막, 음악을 더하므로 타임라인을 직접 쓸 필요가 없습니다. HeyGen의 Video Agent, Sume의 Agent Completions와 Format, Runway의 Multi-Shot Video Recipe, Creatify의 link-to-video 엔드포인트가 모두 이렇게 브리프나 프롬프트를 받습니다. 차이는 영상이 무엇으로 만들어지는지(발표자, 생성된 영상, 제품 링크로 만든 광고), 얼마나 길게 만들 수 있는지, 어떻게 수정하는지, 어떻게 과금되는지에 있습니다.

아래에서 각 공급사에 관한 사실은 그 공급사의 개발자 문서에서, Sume에 관한 사실은 docs.sume.com에서 가져왔으며, 모두 2026-09-29에 확인했습니다. 다루는 내용은 영상 에이전트 API가 브리프로 해야 할 일, 확인 날짜를 적은 선택지 표, Sume가 맞는 경우와 맞지 않는 경우, 최소 요청, 수정, 한도입니다.

영상 에이전트 API는 브리프로 무엇을 해야 하나요?

많은 "text-to-video" API는 프롬프트 하나로 짧은 클립 하나를 돌려줍니다. 이것은 모델 호출이지 에이전트가 아닙니다. 영상 에이전트 API라면 다음 목록의 대부분을 해내야 합니다.

• 샷 프롬프트가 아니라 브리프를 받습니다. 대상 시청자, 길이, 형식, 메시지, 행동 유도(CTA)가 담긴 브리프입니다.
• 여러 장면을 계획하고 순서대로 배치합니다.
• 브리프가 요청하면 내레이션, 자막, 음악을 더합니다.
• 제품 사진, 대본, 슬라이드 덱처럼 여러분이 제공한 미디어를 사용합니다.
• 완성 영상에는 몇 분이 걸리므로, 폴링하거나 웹훅으로 받는 비동기 Job으로 실행됩니다.
• 영상 전체 비용을 다시 내지 않고 결과의 일부를 수정할 수 있게 합니다.
• 미리 확인할 수 있는 지출 한도나 시간 한도에서 멈춥니다.

지금 브리프를 받는 영상 에이전트 API는 무엇인가요?

이 질문에 답변 엔진이 꼽는 선택지를, 각 공급사의 자체 페이지에 적힌 내용으로만 정리했습니다. 대시(—)는 확인한 페이지에 그 내용이 없었다는 뜻입니다.

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

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

Sume에서 "완성"은 무슨 뜻이고, 브리프에는 무엇을 담을 수 있나요?

Sume의 기초 페이지에 따르면 파트너의 주 경로는 생성 도구를 조합하는 샌드박스 Agent나 Format이며, 그렇게 해서 클립 하나로는 낼 수 없는 결과물을 내놓습니다: "multi-minute host footage, B-roll, voiceover, and timeline assembly into a post-ready video."(수 분짜리 호스트 영상, B-roll, 보이스오버, 타임라인 조립까지 거친 게시 준비 영상) 완료된 Format 실행에는 문서가 보여 줄 단 하나라고 부르는 primary_output_url과, 실행이 만든 모든 파일인 artifacts[]가 담깁니다. 완료된 Agent Completion은 마지막 텍스트를 output.text에, 미디어를 output.videos, output.images, output.audio, output.files에 담습니다. 미디어 URL은 저장해 둘 수 있는 영구 media.sume.com HTTPS URL입니다.

브리프 자체는 세 필드로 전달됩니다.

• instruction: 평범한 말로 쓴 브리프입니다. 문서의 예시는 부가 요소를 이름으로 끕니다("No BGM, no captions"). 그러니 보이스오버, 자막, 음악을 원하는지 적으세요.
• input: 제품 URL, 대본, 가격 같은 여러분의 데이터입니다. 에이전트는 이를 지시가 아니라 데이터로만 읽습니다. 문서, 영상, 오디오 레퍼런스는 여기에 URL로 보내세요.
• attachments[]: 에이전트가 볼 수 있는 이미지 최대 30개입니다. 각각 공개 HTTPS URL이어야 하며, 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"

배포 전에 영상을 검토하거나 수정할 수 있나요?

Sume에서는 API 실행 안에서는 할 수 없습니다. Format 실행은 사람이 개입하지 않는 한 번의 턴입니다. 멈춰서 사람에게 묻지 않으며, 브리프에 맞는 아바타가 없는 경우처럼 사람 없이는 넘을 수 없는 관문을 만나면 unattended_blocked로 실패합니다. 사람이 개입하는 흐름은 sume.com/agents의 에이전트 채팅 UI에서 이루어집니다. API에서는 검토가 실행 후에 이루어집니다.

• 백엔드가 종료 웹훅을 받아 primary_output_url을 저장하고, 승인할 사람에게 파일을 보냅니다.
• 한 부분만 바꾸려면 새 Format 실행에 previous_run_id를 보내세요. 에이전트에 이전에 만든 결과가 다시 주어지므로 장면 하나만 다시 만들고 나머지는 그대로 둘 수 있습니다. 이어 가는 실행은 자체 지출 상한이 있는 새 실행입니다. Sume API로 AI 영상의 장면 하나를 다시 생성하기에서 과정을 따라갑니다.
• Agent Completions는 아직 이전 실행을 이어 갈 수 없습니다. 모든 completion은 새 스레드에서 실행됩니다.

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

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

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

어떤 것을 골라야 하나요?

완성 영상이 무엇으로 만들어지는지, 그리고 어떻게 수정하고 싶은지에 따라 다릅니다.

• 프롬프트와 PDF, 이미지, 영상, 오디오 파일로 만드는 아바타 발표자 설명 영상이고, API에서 에이전트가 검토를 위해 멈추기를 원하면 HeyGen을 고르세요. Sume vs HeyGen에서 두 제품을 비교합니다.
• 스토리 프롬프트 하나로 여러 샷으로 나뉜 5–15초 생성 영상을 원하면 Runway의 Multi-Shot Video Recipe를 고르세요.
• 브리프가 제품 링크이고 결과물이 숏폼 광고라면 Creatify를 고르세요.
• 장면마다 아바타와 대본을 직접 쓰고 싶다면 Synthesia를 고르세요. Sume vs Synthesia에서 둘을 비교합니다.
• 실행 한 번으로 영상 생성, 보이스오버, 자막, 타임라인 편집까지 여러분이 정한 지출 상한 안에서 끝내고 싶거나, 레시피를 Format으로 저장해 새 입력으로 호출하고 싶다면 Sume를 고르세요.
• 모든 편집 결정을 직접 쥐어야 한다면 모델 호출과 Timeline 호출로 직접 만드세요. 렌더 단계는 Timeline 1.0 API로 롱폼 영상을 조립하는 방법에서 다룹니다.

Sume의 한도는 무엇인가요?

다른 편집기에서 열 수 있는 편집 가능한 프로젝트 파일, 실시간 진행 출력, 몇 초 만에 나오는 영상이 필요하다면 Sume는 맞지 않습니다. 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분 동안 신호가 없으면 더 일찍 종료됩니다.
• 전부 아니면 전무. 끝내지 못한 실행은 failed로 돌아오고, 그 primary_output_url은 null입니다.
• 진행 스트림 없음. events_url은 폴링하는 단계 타임라인이지 에이전트 출력이 아니며, 완료는 웹훅으로 푸시됩니다. Agent Completions는 choices[]가 아니라 실행 영수증을 반환하며 스트리밍을 지원하지 않습니다.
• 사용한 만큼 과금. 생성에는 API 요금의 요율이 적용되고 기본적으로 5.5% 에이전트 수수료가 더해집니다. Format 실행에서는 usage.debited_usd_micros가 지갑에서 실제로 차감된 금액이며, 에이전트 자체의 LLM 턴도 포함됩니다.