Sume Format을 실행하는 LangChain 영상 생성 도구

Sume용 LangChain 영상 생성 도구는 POST /v1/formats/{handle}/{slug}/runs로 Format 실행을 시작하는 @tool 함수입니다. 에이전트의 브리프를 input으로 넘기고, generation_spend_cap_usd로 지출 상한을 두고, 고정된 Idempotency-Key를 보낸 뒤, 실행 자체는 몇 분이 걸리므로 실행 id를 반환합니다.

Sume 관련 내용은 Format 호출하기 (영문), 실행과 결과 (영문), Sume 기초에서, LangChain 관련 내용은 LangChain의 도구, MCP, MCP 인증 페이지에서 가져왔으며, 모두 2026-09-27에 확인했습니다. Sume에는 LangChain 전용 연동이 없습니다. 직접 작성한 도구에서 HTTPS로 호출하는 방식입니다. TypeScript 백엔드에서 같은 API를 쓰는 방법은 제품에 AI 영상 생성을 임베드하는 방법에서 다룹니다.

모델 호출 대신 Format을 감싸는 이유는 무엇인가요?

Format은 저장해 둔 레시피입니다. 실행마다 Sume는 새 샌드박스를 띄우고, 레시피를 로드하고, 생성 도구를 쓰는 Agent를 실행한 뒤 아티팩트와 선택적 구조화 JSON을 돌려줍니다. Sume 기초 페이지는 Format을 대부분의 파트너가 연동해야 하는 표면이라고 설명합니다. 영상이 필요하다는 판단은 LangChain 에이전트가, 영상을 만드는 방법은 Format이 맡습니다. 직접 만든 Format은 {handle}/{slug}로, 카탈로그 Format은 sume/{slug}로 호출하며, 키에는 formats:write가 있어야 합니다. Format이 처음이라면 Sume Format이란?부터 읽어 보세요.

도구는 어떻게 작성하나요?

LangChain의 @tool 데코레이터는 함수를 도구로 바꿉니다. 타입 힌트는 도구의 입력 스키마를 정의하므로 필수이고, docstring은 모델이 읽는 설명이 됩니다. 아래 두 도구는 실행을 시작하고 그 실행을 다시 읽습니다. 둘 다 create_agent에 넘기세요.

import hashlib, os, requests
from langchain.tools import tool

API = "https://api.sume.com/v1"
AUTH = {"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"}

@tool
def start_video_run(brief: str, product_url: str) -> str:
    """Start a Sume video run for a product. Returns a run id; the video takes minutes."""
    key = "lc-" + hashlib.sha256(f"{product_url}|{brief}".encode()).hexdigest()[:40]
    body = {"input": {"brief": brief, "product_url": product_url}, "generation_spend_cap_usd": 20}
    res = requests.post(f"{API}/formats/acme/product-video/runs", json=body,
                        headers={**AUTH, "Idempotency-Key": key}, timeout=30)
    res.raise_for_status()
    return res.json()["data"]["id"]

@tool
def get_video_run(run_id: str) -> dict:
    """Read a Sume video run. While status is queued or processing, check again later."""
    run = requests.get(f"{API}/format-runs/{run_id}", headers=AUTH, timeout=30).json()["data"]
    videos = [a["url"] for a in run["artifacts"] if a["type"] == "video"]
    return {"status": run["status"], "videos": videos, "error": run["error"]}

요청 본문에는 무엇이 들어가나요?

본문에는 instruction, input, previous_run_id, attachments 중 하나 이상이 있어야 합니다. 이 도구는 input을 보내고 Format의 기본 instruction이 실행되게 합니다.

Idempotency-Key를 인자에서 유도하는 이유는 무엇인가요?

문서는 키를 요청한 시점이 아니라 만들고 있는 대상에서 유도하라고 합니다. LangChain 미들웨어는 실패한 도구 호출을 재시도할 수 있는데, 이때 같은 인자는 같은 키를 만들고 Sume는 두 번째 유료 실행 대신 원래 실행으로 응답합니다. 409 idempotency_key_in_use는 중복 요청이 같은 순간에 도착했다는 뜻입니다. 1초쯤 기다렸다가 다시 보내면 원래 실행을 받습니다.

에이전트는 완성된 영상을 어떻게 받나요?

생성 호출은 영수증과 함께 202로 응답합니다. get_video_run은 GET /v1/format-runs/{run_id}를 읽습니다. queued와 processing은 나중에 다시 확인하라는 뜻이고, completed, failed, canceled, skipped는 최종 상태입니다. artifacts[]에는 실행이 생성한 모든 내구성 있는 파일이 media.sume.com URL로 나열되며, 이 URL은 만료되지 않고 URL을 가진 누구에게나 공개됩니다.

긴 영상은 15~30분짜리 작업이므로 확인 사이에 백오프하되, 간격을 두 배씩 늘려 최대 1분까지 늘리세요. expires_at은 실행이 failed로 강제 종료되는 마감 시각이며, created_at으로부터 최대 90분 뒤입니다. 서버가 communication.webhook_url을 보낼 수도 있으며, 그러면 실행이 완료되거나 실패할 때 Sume가 서명된 영수증 하나를 그 URL로 POST합니다. 문서는 프로덕션 연동에서 result_url 읽기를 백업으로 유지하게 합니다. Sume Format 실행 수명주기를 참고하세요.

대신 LangChain의 MCP 어댑터를 쓸 수 있나요?

단건 생성이라면 쓸 수 있습니다. LangChain의 MCPAdapter는 MCP 서버의 도구를 create_agent로 불러오고, FastMCP Client(url, auth=token) 클라이언트는 bearer 토큰을 보냅니다. langchain.mcp 네임스페이스에는 langchain[mcp]>=1.4.0이 필요하며, 이 네임스페이스는 베타입니다. Sume 호스팅 MCP 도구는 generate_video, jobs_wait처럼 선별된 API 기능을 감싸며, 문서에 나온 도구 목록에는 Format 실행 도구가 없으므로 Format 실행은 여전히 위의 Format API를 거칩니다. Sume 기초 페이지도 호스팅 MCP가 여전히 동작하지만 현재 주 경로는 아니라고 설명합니다.