가이드
Sume 가이드: API, 포맷, 에이전트, 모델, 미디어 도구, 요금을 다룹니다. 답마다 날짜와 출처를 붙였습니다.
OpenAI Responses API MCP 도구로 Sume 호출
Sume 호스팅 MCP 서버를 Responses API에 mcp 도구로 추가하고, Sume API 키는 headers로 보내고, 유료 도구 호출은 실행 전에 승인하세요.
Claude API MCP 커넥터와 Sume: 지금 쓸 수 있는 방법
Claude API의 MCP 커넥터로 Sume 호스팅 MCP에 인증하는 방법은 현재 문서화되어 있지 않습니다. 그 이유와 Agent SDK 같은 대안을 정리했습니다.
Gemini CLI MCP 서버: Sume 호스팅 MCP 추가하기
httpUrl과 환경 변수에서 읽는 API 키 헤더로 Sume 호스팅 MCP 서버를 Gemini CLI에 추가하고, 도구는 허용 목록으로 추린 뒤 호출 전에 확인하세요.
Windsurf MCP 서버: Devin Desktop에 Sume 추가
Windsurf는 이제 Devin Desktop입니다. API 키 헤더로 Sume 호스팅 MCP 서버를 Devin Local 에이전트나 레거시 Cascade 에이전트에 추가하세요.
Cline MCP 원격 서버: Sume 호스팅 MCP 추가하기
type을 streamableHttp로 지정하고 API 키 헤더를 넣어 Sume 호스팅 MCP 서버를 Cline에 원격 서버로 추가하고, 유료 도구는 autoApprove에서 빼 두세요.
Pydantic AI MCP 서버: 에이전트에 Sume 호스팅 도구 연결
MCPToolset과 API 키 헤더로 Pydantic AI 에이전트를 Sume 호스팅 MCP 서버에 연결하고, 도구를 걸러 내고, 유료 호출은 승인 전까지 보류하세요.
Google ADK MCP 도구: McpToolset으로 Sume 서버 연결
McpToolset, API 키 헤더, tool_filter로 Google ADK 에이전트에 Sume 호스팅 MCP 서버를 추가하고, 유료 도구는 실행 전에 확인을 받게 하세요.
Mastra MCP 클라이언트: 에이전트를 Sume 호스팅 MCP에 연결
MCPClient로 Mastra 에이전트를 Sume 호스팅 MCP 서버에 연결하세요. requestInit에 넣는 API 키 헤더, 도구 허용 목록, 유료 호출 승인을 다룹니다.
n8n MCP Client Tool과 Sume: 설정과 SSE 주의점
n8n은 MCP Client Tool 필드를 SSE Endpoint라 부르지만 Sume는 streamable HTTP를 문서화합니다. 설정하고 연결을 테스트한 뒤 유료 호출은 승인받게 하세요.
Dify OpenAPI 커스텀 도구: Sume API 스키마 가져오기
Sume OpenAPI 스키마로 Dify 커스텀 도구를 만드세요. 영상 오퍼레이션 세 개만 남겨 Swagger API 도구로 가져오고, 키는 비밀로 지킵니다.
Power Automate HTTP 요청 API: Sume 실행 시작과 폴링
Power Automate HTTP action으로 Sume API를 호출하세요. Format 실행을 시작하고, Do until 루프로 폴링하고, 키는 Key Vault 시크릿에서 읽습니다.
Bubble API Connector: Sume API로 AI 영상 생성하기
Sume용 Bubble API Connector 설정법입니다. 키는 비공개 헤더에 두고, 수동 응답으로 설정 비용을 없애고, 백엔드에서 Job을 폴링합니다.
Gradio 영상 생성 앱: Sume API 키는 Space 시크릿에
Sume API로 Gradio 영상 생성 앱을 만드세요. 키는 Hugging Face Space 시크릿에 두고, 제너레이터가 Job을 폴링하고, gr.Video가 영상을 재생합니다.
Telegram 영상 생성 봇: Sume Job 후 sendVideo
Telegram 봇은 /video 커맨드를 Sume Job으로 바꿔 곧바로 답한 뒤, Sume의 서명된 웹훅이 도착하면 아티팩트 URL로 sendVideo를 호출할 수 있습니다.
PHP 웹훅 서명 검증: 순수 PHP와 Laravel
PHP에서 Sume 웹훅 검증하기: timestamp.raw_body에 hash_hmac sha256을 적용하고, sume-v1 항목을 나눠 각각 hash_equals로 비교하세요.
Golang 웹훅 서명 검증: HMAC과 hmac.Equal
Go에서 Sume 웹훅 검증하기: io.ReadAll로 본문을 한 번 읽고, 타임스탬프와 원본 바이트에 HMAC-SHA256을 계산한 뒤, 각 sume-v1 항목을 hmac.Equal로 비교하세요.
Sume API로 AI 영상의 장면 하나를 다시 생성하기
AI 영상의 장면 하나를 다시 생성하려면 previous_run_id로 Sume Format 실행을 이어 가며 그 장면을 지정하세요. 그 클립만 다시 만들고 나머지는 그대로 둘 수 있습니다.
Sume Format 실행 실패: 오류 코드, 세부 정보, 대응 방법
실패한 Sume Format 실행은 error.code에 원인을 담습니다. 코드별 details 필드, 청구되는 비용, 이어 갈지 재시도할지를 정리했습니다.
프롬프트 인젝션과 사용자 입력: AI 에이전트 API에 데이터 넘기기
고객 텍스트는 Sume 실행의 instruction이 아니라 input 객체에 넣으세요. 에이전트는 이를 데이터로 읽으라는 안내를 받으며, 문서는 이를 샌드박스가 아닌 신뢰 경계라고 부릅니다.
Sume Format 레시피용 SKILL.md 파일 작성법
Sume Format 레시피는 SKILL.md 파일과 참고 파일로 이뤄집니다. SKILL.md는 짧은 색인으로 두고, 세부 내용은 references/로 옮기고, 패키지 규칙을 지키세요.
Sume 실행이 AI 생성 영상을 전달했는지 확인하는 방법
Sume 실행을 전달 완료로 세기 전에 status와 primary_output_url을 확인하고, filled_by를 읽고, 파일을 프로브하세요. Sume가 검사하는 것과 하지 않는 것을 정리했습니다.
장면 원장으로 실패한 AI 영상 실행의 부분 결과 받기
출력 스키마가 부분 결과를 허용하면 실패한 Sume Format 실행도 만든 장면을 보고합니다. nullable 필드를 쓰고, minItems는 빼고, primary 키를 지정하세요.
If-Match 낙관적 동시성: API로 Sume Format 파일 편집
다른 작성자의 변경을 덮어쓰지 않고 API로 Sume Format 파일을 편집하세요. 쓰기마다 파일의 blob sha를 보내고, If-Match가 패키지 전체를 지킵니다.
API로 AI 영상 워크플로 만들기: Sume Format과 SKILL.md
POST /v1/formats로 Sume Format을 만든 뒤 Contents API로 SKILL.md 레시피를 쓰세요. 요청 필드, slug 규칙, 처리할 오류를 정리했습니다.
AI 영상 워크플로를 다른 팀과 공유: Sume Format 공유 권한
Sume 팀 Format을 다른 팀 워크스페이스와 공유하세요. 공유 권한이 활성화되면 그 팀은 자기 팀 키로 소유자의 주소를 호출하고, 실행 비용도 직접 냅니다.
Sume Format API 한도: 상한, 크기, 타임아웃
문서화된 Sume Format API 한도를 한곳에 모았습니다. 요청과 입력 크기, 첨부 파일, 스키마, 지출 상한, 큐, 실행 기한, 웹훅, 요청 한도입니다.
strict 모드 JSON Schema oneOf 미지원: 위반 항목 고치기
Sume는 OpenAI strict 모드 부분집합을 벗어난 output_schema를 400 output_schema_invalid로 거부합니다. 위반마다 rule을 읽고 oneOf와 nullable을 옮기세요.
Format 목록 API: handle·id로 Sume Format 찾기
GET /v1/formats는 키로 호출할 수 있는 Format을 나열합니다. Format은 {handle}/{slug}나 영구적인 skl_ id로 지정하고, 그 실행은 최신순으로 나열합니다.
AI 에이전트가 지시를 무시했다면? Sume Format 실행 디버깅
Sume Format 실행이 예상과 다르게 동작했을 때 쓰는 체크리스트입니다. 조합된 첫 메시지, 전달된 지시문, 버전, 이벤트, 출력을 차례로 확인합니다.
프로덕션 AI 에이전트 프롬프트 버전 관리: Sume Format
Sume Format은 편집할 때마다 버전이 올라가고, 실행 영수증마다 실제로 실행된 버전이 기록됩니다. 실행을 특정 버전에 고정할 수 없고, 롤백 API도 없습니다.
AI 영상 배치 실패 항목 재시도: Sume 대량 실행 복구
Sume 대량 실행 큐가 완료되면 counts.failed를 읽고, 결과물을 남긴 실패한 자식 실행은 이어 가거나 새 Idempotency-Key로 다시 제출하세요.
UGC 스타일 제품 영상 광고를 대량으로 만드는 도구 비교
입력, 진행자, 언어, 물량에 따라 다릅니다. Arcads, Creatify, HeyGen, Runway, Synthesia, Sume를 API, 요금, 한도 기준으로 비교합니다.
Agent Completions·Format·Scheduled 요청 본문 차이
Sume Format·Scheduled 실행과 Agent Completions는 필드 이름만 같고, 지출 상한 기본값, null, on_active_run, attachments, 스코프 규칙은 다릅니다.
on_active_run으로 Sume AI 에이전트 중복 실행 막기
Sume의 on_active_run 필드는 실행 중에 들어온 두 번째 실행 요청의 처리를 정합니다. 그대로 실행하거나, 건너뛴 실행을 기록하거나, 409를 받고 아무것도 실행하지 않습니다.
Sume MCP vs CLI vs API: AI 에이전트는 무엇을 쓸까
Sume에서 AI 에이전트의 주 경로는 HTTP와 Format API입니다. 호스팅 MCP는 원격 MCP 클라이언트에 맞고, CLI는 셸 에이전트에 맞으며 Avatar 중심입니다.
Sume MCP 서버 OAuth 플로: 디스커버리·동의·PKCE·스코프
Sume 호스팅 MCP 서버는 자체 OAuth를 운영합니다. 401이 디스커버리 메타데이터를 가리키고, 사용자가 mcp.sume.com에서 동의하면 PKCE S256으로 한 시간짜리 토큰을 받습니다.
MCP 도구 호출 타임아웃: 긴 영상 Job은 jobs_wait로
Sume 호스팅 MCP 서버에서 jobs_wait 호출 한 번은 최대 55초까지 대기합니다. 긴 영상 Job은 나눠서 기다리고, id는 최대 20개까지 묶되 다시 제출하지 마세요.
Sume MCP 도구 목록: 읽기·쓰기·유료로 나눈 호스팅 도구
Sume MCP 도구를 계열별로 정리했습니다. 읽기만 하는 호스팅 도구, 쓰는 도구, 유료 Job을 시작하는 도구, 호스팅 MCP에 아예 없는 도구 이름을 구분합니다.
Sume MCP insufficient_scope·누락 도구·타임아웃 해결
Sume MCP의 insufficient_scope 오류는 OAuth 세션에 mcp:write가 없다는 뜻입니다. mcp_health부터 호출한 뒤 스코프, 누락된 도구, 타임아웃을 해결하세요.
MCP 프로그래밍 방식 도구 호출: Sume script_run 동작 방식
script_run은 Sume 호스팅 MCP의 프로그래밍 방식 도구 호출입니다. 짧은 JavaScript 프로그램이 호출 예산과 유료 예산 안에서 도구를 반복하거나 병렬로 호출합니다.
영상 편집 MCP 서버: AI 에이전트로 트림·필터·조립하기
Sume 호스팅 MCP 서버는 AI 에이전트에 영상 편집 도구를 제공합니다. 검사, 프레임, 트림, 필터, 오디오 분리, 합성, Timeline 렌더가 각각 Job으로 실행됩니다.
Sume 에이전트 실행 오류: action_run_in_progress 등
스케줄 실행이 이미 진행 중인데 reject를 보내면 409 action_run_in_progress, ID가 내 Agent Completion 실행이 아니면 404 agent_run_not_found입니다.
Sume API로 스케줄 에이전트 실행 목록 조회: 스케줄 점검하기
GET /v1/actions(limit, status, trigger_type)로 Sume 스케줄을 나열하고 각 실행 기록은 커서로 넘기며, cron과 API 실행은 trigger.source로 구분하세요.
이미지 입력·JSON 출력 에이전트 API: Agent Completions
Sume Agent Completions에 이미지를 input_image 파트나 attachments로 보내고, output_schema를 바인딩해 완료된 실행의 output에서 타입 있는 JSON을 읽으세요.
CI와 헤드리스 서버에서 Sume CLI 실행하기
CI에서는 버전을 고정한 릴리스 바이너리, 시크릿 저장소의 SUME_API_KEY, 격리된 SUME_CONFIG_DIR, doctor 사전 점검, --json 출력으로 Sume CLI를 실행하세요.
Sume CLI 명령어 레퍼런스: 계정, Job, 에셋, skills
Sume CLI에는 생성 외에도 로그인과 계정, health·doctor 점검, 스키마 탐색, Job, 에셋, 배치 헬퍼, skills, 별칭 명령어가 있습니다.
Sume CLI가 안 될 때: 로그인·API 베이스·Job·미디어 해결법
Sume CLI가 안 될 때는 읽기 전용 점검 네 가지를 먼저 실행한 뒤, 키 누락, 잘못된 API 베이스, 끝나지 않은 Job, 거부된 미디어 URL 중 해당하는 원인을 고치세요.
Image-to-Video API: 첫 프레임과 마지막 프레임 지정
first_frame과 선택적 last_frame을 담은 frame_images를 POST /v1/videos로 보내세요. 각 프레임을 받는 Sume 모델, 우선순위, 거부되는 경우를 정리했습니다.