Dify OpenAPI 커스텀 도구: Sume API 스키마 가져오기

Dify에서 Sume API를 커스텀 도구로 호출하려면 Integrations > Tools를 열고 Swagger API를 고른 뒤, createVideoGeneration, getVideoGeneration, getApiJobResult 세 오퍼레이션만 남긴 Sume OpenAPI 스키마 사본을 붙여 넣으세요. Dify는 스키마에서 도구 인터페이스를 생성하고, 각 도구에 operationId를 이름으로 붙입니다.

Dify 관련 내용은 Dify의 도구, Tool 노드, HTTP Request 노드, 에이전트, 플러그인 페이지에서, Sume 관련 내용은 API 레퍼런스, 영상 생성 (영문), Job과 결과 (영문), 인증 문서와 OpenAPI 문서에서 가져왔으며, 모두 2026-09-27에 확인했습니다. Sume에는 Dify 플러그인이 없습니다. 이 도구는 api.sume.com으로 일반 HTTPS 호출을 보냅니다. 스펙을 내려받아 살펴보는 방법은 Sume API OpenAPI 스펙에서 다룹니다.

Dify 도구에는 어떤 Sume 오퍼레이션을 남겨야 하나요?

Dify는 URL에서 스키마를 가져올 수도 있으며, Sume의 라이브 스키마는 https://api.sume.com/reference/json입니다. 스키마 전체를 가져오면 유료 생성 경로를 포함해 스키마의 모든 오퍼레이션이 도구에 들어갑니다. 영상 도구에는 세 개면 됩니다.

Sume 스키마에서 그 오퍼레이션만 남기려면 어떻게 하나요?

문서에 나온 명령 curl https://api.sume.com/reference/json -o sume-openapi.json으로 스키마를 내려받으세요. 그다음 세 오퍼레이션, 그 오퍼레이션이 참조하는 모든 컴포넌트 스키마, securitySchemes 두 개를 남기고, 출력 파일을 Swagger API 대화상자에 붙여 넣으세요.

import json, re

KEEP = {"createVideoGeneration", "getVideoGeneration", "getApiJobResult"}
REF = re.compile(r"#/components/schemas/([\w.-]+)")
spec = json.load(open("sume-openapi.json"))
paths = {}
for path, ops in spec["paths"].items():
    for method, op in ops.items():
        if isinstance(op, dict) and op.get("operationId") in KEEP:
            paths.setdefault(path, {})[method] = op
schemas = spec["components"]["schemas"]
todo, keep = REF.findall(json.dumps(paths)), set()
while todo:
    name = todo.pop()
    if name not in keep:
        keep.add(name)
        todo += REF.findall(json.dumps(schemas[name]))
trimmed = {
    "openapi": spec["openapi"], "info": spec["info"], "servers": spec["servers"],
    "paths": paths,
    "components": {"securitySchemes": spec["components"]["securitySchemes"],
                   "schemas": {name: schemas[name] for name in keep}},
}
json.dump(trimmed, open("sume-video-tools.json", "w"), indent=2)

Sume API 키는 어디에 넣나요?

모든 호출에는 키가 Authorization: Bearer나 x-api-key 중 하나로 실려야 하며, 둘 다 실리면 안 됩니다. 둘 다 담긴 요청은 401 unauthorized로 거부됩니다. 줄인 스키마에는 bearerAuth와 apiKey 두 스킴이 모두 선언되어 있습니다. Dify 문서는 도구에 인증이 필요하면 Tool 노드나 에이전트의 도구 설정에서 기존 자격 증명을 고르거나 새로 만들라고 안내합니다. Dify의 도구 페이지는 Swagger API 도구 자체의 인증 필드를 설명하지 않으므로, 자격 증명이 Sume의 두 헤더 중 하나로 나가는지 확인하세요.

• 비용 없이 확인하세요. 지어낸 id로 getVideoGeneration을 호출합니다. 401이면 키가 도착하지 않았거나 유효하지 않은 것이고, 404면 키는 동작했고 그 Job이 워크스페이스에 없다는 뜻입니다.
• 키를 스키마 텍스트, 프롬프트, 입력 필드에 넣지 마세요. Dify는 숨김 입력 필드도 비밀이 아니라고 설명하며, API 키에는 환경 변수를 쓰라고 합니다.
• 키가 로그나 채팅 기록에 노출되면 교체하세요.

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

여러 턴에 걸쳐 받습니다. createVideoGeneration은 Job id를 즉시 반환하고, 영상 생성은 보통 30초에서 몇 분이 걸립니다. 그러니 요청 하나 안에서 반복하지 말고, 에이전트가 id를 알려 준 뒤 이후 메시지에서 다시 확인하게 하세요. Dify의 Maximum Iterations 설정은 요청 하나가 거치는 추론·행동 사이클 수의 상한이며, 값이 높을수록 지연 시간과 토큰 비용이 늘어납니다.

• model과 prompt는 필수이며, sume/auto를 쓰면 Sume가 모델을 고릅니다. v1 모델이 거부하는 size, seed, 비어 있지 않은 provider.options는 빼라고 에이전트에게 알려 주세요.
• status가 completed가 되면 getApiJobResult를 호출하세요. data.result.artifacts의 각 항목에는 사용자에게 보여 줄 media.sume.com의 url이 있습니다.
• getVideoGeneration의 unsigned_urls는 보여 주지 마세요. 이 URL은 GET /v1/videos/{id}/content를 가리키며, 문서는 이 엔드포인트를 API 키와 함께 호출합니다.

HTTP Request 노드가 더 잘 맞는 때는 언제인가요?

호출이 모델의 선택이 아니라 워크플로의 고정 단계일 때입니다. HTTP Request 노드에서 API Key 인증을 Bearer 하위 유형으로 쓰면 Authorization: Bearer <token>이 추가되며, Secret 유형 환경 변수는 워크플로 실행 로그와 노드의 요청 로그에서 가려집니다. 이 노드의 재시도 설정은 실패한 요청을 최대 10번까지 재시도할 수 있으므로, POST /v1/videos에는 Idempotency-Key 헤더를 보내세요. 같은 키로 다시 보내면 두 번째 Job을 시작하는 대신 원래 Job이 돌아옵니다. 폴링 규칙은 영상 생성 Job 상태 API 폴링하기에 있습니다.