영상 배경 음악 API: API 키 없는 Sume BGM 카탈로그

Sume의 배경 음악 API는 API 키 없이 쓰는 큐레이션 트랙 카탈로그입니다. GET https://api.sume.com/v1/bgm/catalog는 트랙 66개를 audio_url, 길이, 템포, 에너지, license와 함께 나열하고, POST /v1/bgm/pick은 설명한 분위기나 제품에 맞는 트랙 하나를 골라 줍니다. 두 호출 모두 Sume API 키가 필요 없습니다.

API 레퍼런스는 BGM 라우트를 공개 라우트로 나열하며, 각 라우트의 설명은 Sume API 레퍼런스에 있습니다. 모두 2026-09-27에 확인했습니다. 트랙 수와 매칭 규칙은 같은 날 Sume의 카탈로그 코드에서 가져왔으며, 현재 동작은 바뀔 수 있습니다. 보이스오버 아래에 트랙을 믹싱하려면 API로 영상에 배경 음악 넣기를 참고하세요.

BGM 엔드포인트에는 무엇이 있고, API 키가 필요한가요?

어느 엔드포인트도 키가 필요 없습니다. 문서는 Sume API 키 없이 동작하는 /v1 라우트 여섯 개를 나열하는데, 그중 세 개가 배경 음악(BGM) 카탈로그이므로 일반 HTTPS 요청이면 충분합니다. 카탈로그는 Sume가 큐레이션하며, 사용자별 업로드 기능은 없습니다.

curl "https://api.sume.com/v1/bgm/categories"

curl "https://api.sume.com/v1/bgm/catalog?category=tech&energy=upbeat&limit=5"

트랙마다 어떤 정보가 들어 있나요?

tracks[]의 모든 행에는 같은 필드가 있고, 응답에는 카탈로그 버전(현재 bgm_catalog_v3)이 담깁니다. API 레퍼런스에 따르면 기존 퍼스트파티 id는 바뀌지 않으므로, Sume 오리지널 트랙의 id는 저장해 두어도 안전합니다.

• id, slug, name, description, category가 있습니다.
• audio_url과 preview_url이 있습니다. 현재 코드에서는 둘 다 같은 MP3 파일을 가리킵니다.
• duration_seconds(카탈로그 전체 기준 30–262초), bpm(62–132), energy(calm, upbeat, dramatic, neutral 중 하나), loopable(트랙 66개 모두 true)이 있습니다.
• license, attribution, source_name, source_url, featured가 있으며, 다음 섹션에서 다룹니다.
• 매칭에 쓰이는 목록인 moods, genres, tags, video_genres, product_categories, locales가 있습니다. 태그에는 영어 단어와 한국어 단어가 섞여 있으며, 트랙 9개는 로케일이 ko 하나뿐입니다.

카탈로그 트랙에는 어떤 라이선스가 붙어 있나요?

트랙을 쓰기 전에 트랙마다 license를 확인하세요. 카탈로그에는 다음 두 가지 값이 쓰입니다.

• sume-original(트랙 48개): Sume가 직접 만든 루프로, https://media.sume.com/assets/bgm/에서 제공됩니다. attribution은 null이고 source_name은 Sume입니다.
• cc-by-4.0(트랙 18개): CC BY 4.0 라이선스의 서드파티 트랙으로, Sume로 복사하지 않고 저작자의 공식 URL로 연결합니다. featured로 표시되며, 트랙마다 attribution 문자열이 있습니다.
• Sume API 레퍼런스는 이런 CC BY 트랙을 공개적으로 사용할 때마다 track.attribution을 함께 남기라고 안내하므로, 그 문자열을 트랙 id와 함께 저장하세요.

카탈로그는 어떻게 필터링하나요?

쿼리 파라미터 category, mood, genre, energy, tag, video_genre, product_category, locale 중 필요한 것을 붙이고, limit(1–200)도 더할 수 있습니다. energy는 네 가지 값 중 하나를 받습니다. 현재 코드에서는 limit의 기본값이 100이고, 보낸 필터를 모두 만족하는 트랙만 나오며, 나머지 필터는 대소문자를 구분하지 않고 단어 일부만 맞아도 일치로 보고, featured 트랙이 먼저 정렬됩니다.

GET /v1/bgm/categories는 아래 카테고리 9개를 반환하며, 각 카테고리에는 name_ko에 담긴 한국어 라벨도 있습니다.

/v1/bgm/pick은 트랙을 어떻게 고르나요?

context 객체에 영상을 설명하세요. API 레퍼런스는 점수를 매기는 신호로 분위기, 장르, 에너지, 태그, 제품 카테고리, 사용자 프롬프트를 꼽으며, 현재 코드는 video_genre, locale, duration_seconds에도 점수를 매깁니다. 선택 필드인 min_score와 auto_expand로 매칭을 얼마나 엄격하게 할지 정합니다.

• 최고 점수가 같은 트랙끼리는 무작위가 아니라 결정적으로 가려지므로, 같은 context에는 같은 트랙이 나옵니다.
• 현재 코드에서 엄격한 매칭에는 min_score(기본값 6) 이상의 점수가 필요합니다. 기본값대로 auto_expand가 켜져 있으면, 엄격한 매칭에 실패했을 때 먼저 3점 이상의 점수를 모두 받아들이고, 그다음에는 energy를 보냈다면 energy를 빼고 점수를 다시 매기며, 그다음에는 컨텍스트를 무시하고 카탈로그 전체에서 고릅니다. 마지막 두 단계에서는 relaxed_filters에 각각 energy와 mood_and_tags가 기록됩니다.
• 응답에는 track과 score 외에 matched_signals, relaxed_filters, candidate_count, catalog_version, match_tier가 담깁니다. match_tier는 strict, widened, 또는 catalog_fallback이며, catalog_fallback은 auto_expand가 false이고 min_score에 이른 트랙이 없을 때 나옵니다.
• pick 결과로 CC BY 트랙이 나올 수 있으므로 먼저 license를 확인하세요.

curl -X POST https://api.sume.com/v1/bgm/pick \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "mood": "calm",
      "energy": "calm",
      "product_category": "skincare",
      "user_prompt": "30-second product ad for a night cream"
    }
  }'

카탈로그 트랙을 Timeline 사운드트랙으로 쓸 수 있나요?

현재 코드에서는 Sume 오리지널 트랙만 쓸 수 있습니다. Timeline 1.0은 모든 미디어 URL이 Sume 미디어 호스트에 있는지 검사하고, 다른 곳에 호스팅된 soundtrack.url은 400 unsupported_media_source로 거부합니다. sume-original 트랙의 audio_url은 media.sume.com에 있어 이 호스트 검사를 통과하지만, cc-by-4.0 트랙의 URL은 저작자의 사이트에 있으므로 Timeline이 거부합니다.

과금되지 않는 POST /v1/timeline-1.0/plan은 Job을 만들거나 크레딧을 예약하지 않고 같은 Sume 호스트 URL 검사를 실행하므로, 유료 렌더 전에 plan으로 타임라인을 먼저 테스트하세요. 맞는 카탈로그 트랙이 없으면 Music Router로 트랙을 생성하세요.