Sume API 미디어 URL 규칙: 엔드포인트별 허용 URL

Sume API가 받는 미디어 URL은 두 종류입니다. 대부분의 생성 엔드포인트와 자막 엔드포인트, Format·에이전트 첨부는 가져올 수 있는 공개 HTTPS URL을 받고, 미디어 도구(트림, 오디오 분리, 필터, 프레임, 검사, Timeline 경로)는 이전 Sume Job의 출력처럼 이미 워크스페이스에 속한 media.sume.com URL만 받습니다.

아래 표는 2026-09-27에 확인한 Sume의 미디어 입력 페이지, 엔드포인트별 문서 페이지, OpenAPI 레퍼런스를 바탕으로 합니다. 아바타, 페이스 스왑, 자막 필드와 Format 첨부가 동작하는 방식은 영상 API 미디어 입출력에서 다루며, 이 글은 엔드포인트별 규칙을 정리합니다.

엔드포인트마다 어떤 URL을 받나요?

공개 HTTPS는 공개 인터넷에서 가져올 수 있는 HTTPS URL을 뜻합니다. 워크스페이스 media.sume.com은 그 호스트에 이미 있는 워크스페이스의 산출물이나 에셋을 뜻하며, 다른 호스트는 거부됩니다. 각 행은 해당 엔드포인트를 다루는 글로 연결됩니다.

공개 HTTPS URL은 어떤 URL인가요?

문서는 이를 가져올 수 있는 공개 HTTPS URL이라고 부릅니다. 공개 인터넷에서 보낸 익명 요청으로 파일을 불러올 수 있어야 한다는 뜻입니다.

• localhost, 사설 네트워크 URL, HTTPS가 아닌 URL, 서명된 URL이나 비공개 URL은 생성 제출 전에 거부되며, 콘텐츠 타입이 맞지 않는 URL도 마찬가지입니다.
• 현재 코드에서는 첨부를 제외한 표의 모든 URL 필드가 URL에 포함된 자격 증명, 기본값인 443이 아닌 포트, .local, .internal, .test로 끝나는 호스트 이름도 거부하며, URL 길이를 2,048자로 제한합니다.
• Format과 에이전트 첨부는 실행을 만들 때 가져오므로 인증 없이 접근할 수 있어야 합니다. 호스트에 연결할 수 없거나, 핫링크 보호가 걸려 있거나, 2xx가 아닌 응답이 오면 생성 요청이 502 attachment_fetch_failed로 실패합니다.

트림, 프레임, Timeline은 왜 URL을 거부하나요?

미디어 도구는 공개 인터넷에서 파일을 가져오지 않으므로, https://example.com/clip.mp4 같은 호스트 밖 URL은 접수 단계에서 거부됩니다. 이때 반환되는 URL 관련 코드는 다음과 같습니다.

• unsupported_media_source: URL이 Sume 미디어 호스트에 있지 않은 경우입니다.
• source_not_found: 더 이상 없거나 다른 워크스페이스에 속한 media.sume.com URL인 경우입니다.
• unsupported_media_type: 트림, 오디오 분리, 필터에서 파일의 HEAD 응답이 영상이 아닌 경우입니다.
• POST /v1/video-frames에서는 media.sume.com에 있지 않은 video_url이 일반 스키마 오류인 400으로 처리됩니다.

비용 없이 URL을 테스트할 수 있나요?

네. POST /v1/video-filter/check는 필터 인코딩과 같은 Sume 호스트·HEAD 프리플라이트를 실행하고, 400 대신 진단 정보를 반환합니다. Job을 만들지도, 크레딧을 예약하지도 않습니다. POST /v1/timeline-1.0/plan은 타임라인 전체에 대해 Sume 호스트 URL 검사를 실행하며, 이것도 과금되지 않습니다.

curl -X POST https://api.sume.com/v1/video-filter/check \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "ops": [{ "op": "dim", "amount": 0.45 }]
  }'

파일을 media.sume.com에 두려면 어떻게 하나요?

이전 Sume 출력에서 시작하세요. Sume는 생성된 출력을 결과에 노출하기 전에 Sume 소유 미디어 URL로 미러링하며, 완료된 Job에는 그 파일이 media.sume.com 아래의 산출물로 담깁니다. 생성된 클립, 자막을 입힌 영상, 앞서 트림한 영상을 다음 미디어 도구에 넣을 수 있습니다. POST /v1/videos 클립이라면 마지막 프레임으로 클립 잇기에서 보여 주듯 GET /v1/jobs/{id}/result에서 산출물을 읽으세요.

• Sume의 에셋 업로드 경로는 구현되어 있지만 공개 OpenAPI에서 숨겨져 있으며, 문서는 이를 공개 계약으로 취급하지 말라고 안내합니다.
• 원본 프로바이더 URL이 아니라 Sume URL을 저장하세요. 원본 프로바이더 URL과 프로바이더 작업 URL은 공개 결과 계약에 포함되지 않습니다.