사용 가이드
HiAPI에서 전자상거래 제품 이미지용으로 mureka-9.5/instrumental 사용하기
HiAPI 오디오 API로 반복 가능한 BGM에서 제품 영상까지의 파이프라인 구축하기
이 페이지에서
제품 비주얼에 독립적인 BGM 레이어가 필요한 이유
대부분의 전자상거래 상품 카탈로그는 두 개의 독립된 생산 라인으로 조립됩니다. 하나는 제품 정지 이미지와 짧은 클립을 만드는 비주얼 라인이고, 다른 하나는 보통 마지막 순간까지 미뤄지는 임시 오디오 라인입니다. 결과는 예측하기 쉽습니다. 수십 개의 SKU가 같은 세 곡의 라이브러리 음악을 공유하고, 클립마다 음량이 들쭉날쭉하며, 마케팅 리뷰 회의에서 아무도 답하고 싶지 않은 라이선스 문제가 남습니다.
배경 음악을 별도의 레이어로 다루면 이런 문제가 해결됩니다. 완성된 영상에 오디오를 억지로 붙이는 대신 제품 카테고리별로 트랙을 생성하고, 재사용 가능한 자산으로 저장한 뒤 렌더링 시점에 믹싱하는 것입니다. 이런 분리는 실질적인 이점이 있습니다.
- 재사용성. 한 트랙이 해당 카테고리의 모든 SKU를 커버하므로 제품 클립 백 개에 오디오를 백 번 생성할 필요가 없습니다.
- 일관성. 고정된 트랙은 고정된 음량과 고정된 루프 지점을 의미하며, 덕분에 제품 영상 한 화면이 재생 목록이 아니라 하나의 브랜드처럼 보입니다.
- 교체 가능성. 비주얼이 바뀌면 오디오를 다시 생성할 필요 없이 다시 믹싱만 하면 되고, 오디오가 바뀌면 비주얼은 그대로 둘 수 있습니다.
- 출처 명확성. 생성된 기악 트랙은 제3자 샘플 권리 정리 문제가 없으며, 스토어에 변형이 필요하면 다시 생성할 수 있습니다.
이것이 생성형 기악 엔드포인트가 실제 생산 파이프라인에서 자리를 차지하는 이유입니다. 기악 출력은 화면 텍스트나 내레이션과 주의를 다투는 보컬이 없고, 텍스트 프롬프트는 브랜드 가이드라인에 이미 있는 어휘(차분함, 미니멀, 활기, 임상적)로 분위기를 설명할 수 있습니다.
이 가이드의 나머지 부분은 이 레이어를 구축합니다. HiAPI를 통해 mureka-9.5/instrumental로 트랙을 생성한 뒤, 클립마다 개별 예술 작업을 하는 대신 배치 작업으로 실행할 수 있는 방식으로 짧은 제품 영상에 믹싱합니다.
mureka-9.5/instrumental이 제공하는 것
기능적으로 mureka-9.5/instrumental은 텍스트로 음악을 생성해 순수 기악 트랙을 반환하는 모델입니다. 제거할 보컬 스템도, 관리할 가사 입력도 없습니다. 원하는 음악을 설명하면 오디오를 돌려받습니다.
HiAPI로 호출할 때 이 모델은 플랫폼의 다른 부분과 동일한 통합 방식을 따릅니다. 즉 하나의 자격 증명, 하나의 엔드포인트 패밀리, 그리고 저장하고 재사용할 수 있는 응답입니다. 오디오를 위해 별도 계정이나 별도 과금 관계를 설정할 필요가 없으며, 생성된 트랙은 파이프라인이 이미지와 비디오 외에 생산하는 또 하나의 자산일 뿐입니다.
전자상거래 사용 사례에서 특히 중요한 특성이 몇 가지 있습니다.
- 순수 기악 출력. 제품 영상은 보통 짧고 무음 시청 환경에 놓입니다. 보컬이 없는 트랙은 주의를 제품에 붙잡아 두며 자막과 충돌하지 않습니다.
- 프롬프트 기반 분위기. 카테고리 수준의 분위기(예: 생활용품은 따뜻한 어쿠스틱, 전자제품은 맑은 퍼커션)를 수작업으로 곡을 고르는 대신 재사용 가능한 프롬프트로 고정할 수 있습니다.
- 자산 형태의 출력. 결과물은 저장, 명명, 버전 관리, 재사용이 가능한 오디오 자산이며, 이미지 렌더링과 동일한 수명 주기를 가집니다.
모델 페이지 mureka-9.5/instrumental은 클라이언트 코드를 작성하기 전에 현재 요청 필드, 지원 옵션, 응답 구조를 확인하는 권위 있는 위치입니다. 이 가이드는 의도적으로 파이프라인 수준에 머뭅니다. 필드 이름과 사용 가능한 옵션은 계속 진화하므로, 통합은 블로그 글의 가정을 베끼는 대신 문서에 기술된 계약을 기반으로 구축해야 합니다.
범위에 대한 참고 사항: 기악 BGM은 하나의 레이어일 뿐 전체 사운드트랙이 아닙니다. 제품 영상에 내레이션이나 효과음 세트가 필요하다면 그것은 별개의 관심사이며, 이 엔드포인트에 생성하도록 요구할 것이 아니라 음악 베드 위에 합성해야 합니다.
제품 카테고리별 프롬프트와 트랙 사양 설계
생성형 오디오에서 가장 흔한 실패 모드는 구조가 없는 프롬프트가 기술적으로는 합격이지만 브랜드에는 맞지 않는 결과물을 내놓는 것입니다. API를 호출하기 전에 소수의 카테고리 프로필을 정의해 이 문제를 해결하세요.
SKU별 프롬프트가 아닌 카테고리 프로필 수립
상품 카탈로그를 관리 가능한 오디오 카테고리 그룹으로 나누세요. 중형 스토어라면 보통 다섯에서 열다섯 개입니다. 각 카테고리마다 분위기, 악기 힌트, 템포 범위, 피해야 할 것을 적어 두세요. 프로필은 팀 전체가 검토할 수 있는 문서이며 프롬프트 템플릿과 일대일로 대응합니다.
{category} 제품 영상용 기악 배경 음악.
분위기: {mood}. 악기 구성: {instruments}.
템포: {tempo_range}. 편곡을 일정하게 유지하고 루프하기 쉽게 만들 것.
보컬 없음. 갑작스러운 강약 변화 없음.
분위기뿐 아니라 편집을 위해 규격화하기
프롬프트는 트랙이 어떻게 사용될지를 담아야 합니다. 나중에 보답이 돌아오는 두 가지 세부 사항이 있습니다.
- 일정한 에너지. 제품 클립은 짧습니다. 처음 10초를 모두 빌드업에 쓰는 트랙은 클립에 음악이 거의 남지 않게 합니다. 편곡이 일관되게 유지되도록 요구하세요.
- 루프 용이성. 더 긴 클립을 채우기 위해 트랙을 루프할 계획이라면, 딱딱한 조성 전환이 없는 안정적이고 반복적인 느낌을 요구하세요. 이를 위해 설계된 트랙을 루프하는 것이 임의의 트랙을 크로스페이드하는 것보다 훨씬 쉽습니다.
트랙 길이를 미리 결정하기
트랙 길이는 사후 추가가 아니라 사양 결정입니다. 두 가지 전략이 유효합니다.
- 명목 클립 길이에 맞추고 약간 트리밍합니다. 한 카테고리의 모든 클립 길이가 같을 때 적합합니다.
- 카테고리마다 더 긴 베드를 생성하고 클립에 맞춰 루프하거나 트리밍합니다. 길이가 다양하고 재사용 가능한 자산 하나만 쓰고 싶을 때 적합합니다.
대형 카탈로그에서는 두 번째 방식이 보통 운영 투입이 적지만, 루프를 염두에 두고 설계했을 때만 그렇습니다.
사양을 기록하기
각 프로필을 프롬프트 템플릿과 함께 버전 관리에 넣고 카테고리, 템플릿, 예상 트랙 길이를 명시하세요. 주방용품 클립이 왜 그렇게 들리는지 누군가 물으면, 답은 기억이 아니라 파일 하나입니다.
HiAPI로 API 호출하기
호출 자체는 파이프라인에서 가장 작은 부분입니다. 프롬프트 조립, 자산 명명, 저장 등 주변의 모든 것이 결정적이 되도록 구성하세요.
자격 증명과 클라이언트 설정
HiAPI 키를 환경 변수에 저장하고 클라이언트의 한 곳에서 불러오세요. 자격 증명을 여러 스크립트에 흩뿌리지 마세요.
export HIAPI_API_KEY="your_key_here"
기본 URL과 키를 작은 공유 모듈에 넣어 일회성 테스트든 전체 배치든 모든 작업이 같은 구성을 사용하게 하세요.
프로필에서 요청 조립하기
코드에 프롬프트를 직접 쓰지 말고 카테고리 프로필을 불러와 프롬프트 템플릿을 렌더링한 뒤 이를 바탕으로 요청을 구성하세요. 요청에는 다음이 포함되어야 합니다.
- 렌더링된 프롬프트,
- 프로필에 정의된 목표 트랙 특성,
- 그리고 나중에 작업을 추적하는 데 필요한 식별자(카테고리, 프로필 버전).
요청 페이로드를 확정하기 전에 모델 페이지에서 mureka-9.5/instrumental의 정확한 요청 필드를 확인하고, 코드를 해당 문서가 설명하는 구조에 고정하세요.
응답을 값이 아닌 자산으로 다루기
생성 호출은 오디오 자산과 식별자를 반환합니다. 두 가지 습관이 이를 관리 가능하게 유지합니다.
- 즉시 영구 저장.
bgm/{category}/{profile_version}/{job_id}.wav처럼 결정적 키 이름으로 자체 스토리지에 다운로드하세요. 원격 URL이 안정적으로 유지되리라 의존하지 마세요. - 메타데이터 기록. 프롬프트, 프로필 버전, 작업 식별자, 반환된 길이를 파일과 함께 저장하세요. 트랙을 다시 생성해야 할 때 동일한 요청을 재현할 수 있습니다.
실패를 재시도 가능/불가능으로 분류하기
일시적 실패(백오프 재시도)와 요청 자체의 문제(잘못된 필드, 거부된 프롬프트)를 구분하세요. 후자는 재시도해도 같은 방식으로 실패합니다. 잘못된 페이로드를 백 번 재시도하는 배치 작업은 빠르게 실패하고 문제 있는 프로필을 보고하는 것보다 훨씬 나쁩니다.
트랙을 제품 영상에 믹싱하기
믹싱은 인지 품질의 상당 부분이 오가는 지점입니다. 갑자기 시작하거나, 루프 지점에서 튀거나, 스토어의 다른 클립보다 큰 오디오는 트랙 자체가 괜찮더라도 조잡하게 들립니다.
길이를 의도적으로 맞추기
렌더링 전에 클립 길이와 트랙 길이를 비교하세요.
- 트랙이 클립보다 김: 시작이 아니라 끝에서 트리밍하세요. 중간에서 시작하면 인트로를 잃고 불안정한 구간에 떨어지기 쉽습니다.
- 트랙이 클립보다 짧음: 루프하되 루프용으로 설계된 구간에서만 루프하세요. 이음매에 짧은 크로스페이드를 넣어 들리는 팝을 피하세요.
- 거의 같음: 그래도 마지막 1초에 짧은 페이드 인/아웃을 넣어 오디오가 딱딱하게 시작하거나 멈추지 않게 하세요.
음량을 파이프라인 설정으로 제어하기
음량은 클립별 믹스 결정이 아니라 모든 자산에 적용하는 고정 목표여야 합니다. 믹싱 전에 음악 베드를 일관된 레벨로 정규화하고, 내레이션이 있다면 해설이 명료하게 들리도록 약간 낮추세요. 소스 트랙을 한 번만 정규화했으므로 파생된 모든 클립이 같은 기준을 물려받습니다.
한 단계의 결정적 작업으로 믹싱하기
클립과 트랙을 받아 최종 파일을 내놓는 한 줄 명령이 파이프라인을 재현 가능하게 만듭니다.
ffmpeg -i clip.mp4 -stream_loop -1 -i bgm.wav \
-filter_complex "[0:a]anull[a0];[1:a]afade=t=in:st=0:d=0.5,afade=t=out:st=9.5:d=0.5[a1];[a0][a1]amix=inputs=2:duration=first" \
-shortest -c:v copy -c:a aac out.mp4
실제 길이와 클립에 오디오가 있는지에 따라 필터 체인을 조정하되 형태는 유지하세요. 즉 입력은 하나, 출력은 하나, 매개변수는 손으로 입력하는 것이 아니라 작업 사양에 따라 구동됩니다.
소스 자산 보존하기
생성된 트랙과 믹싱된 영상을 별도로 저장하세요. 영상은 파생 산출물이고, 트랙이야말로 재사용 가능한 것입니다. 저장된 트랙에서 영상을 다시 생성하는 것은 빠르지만, 트랙을 덮어썼기 때문에 다시 생성하는 것은 빠르지 않습니다.
수작업 편집 없이 SKU 전반 배치 처리하기
클립 하나에서 전체 카탈로그로 확장하는 것은 주로 데이터 문제입니다. 각 클립의 단계가 매개변수화되어 있으면 배치 레이어는 얇습니다.
매니페스트로 작업 구동하기
작업을 데이터로 기술하세요. 출력마다 한 행씩, SKU, 클립 경로, 카테고리, 프로필 버전을 포함합니다. 러너는 매니페스트를 읽고, 카테고리를 트랙으로 해석하고(캐시 미스일 때만 생성), 영상을 렌더링합니다. 어떤 단계도 사람이 트랙을 고르도록 요구해서는 안 됩니다.
카테고리와 프로필 버전별로 트랙 캐시하기
트랙은 비싸고 재사용 가능한 부분입니다. 캐시 키를 카테고리 더하기 프로필 버전, 그리고 프롬프트에 영향을 주는 옵션으로 설정하고 해당 카테고리의 모든 SKU에서 재사용하세요. 프로필을 수정하면 버전 번호를 올려 오래된 트랙이 새 비주얼과 조용히 재사용되지 않게 하세요.
재렌더링을 일상 경로로 다루기
비주얼은 오디오보다 자주 바뀝니다. 제품 이미지가 갱신될 때 기대되는 동작은 트랙은 유지하고 영상만 다시 믹싱하는 것입니다. 매니페스트를 설계해 클립 변화가 영상 산출물만 재설정하고 트랙 캐시는 따뜻하게 유지되게 하세요. 재렌더링은 저렴하고 평범하며 안전하게 배치 실행할 수 있어야 합니다.
배치 전체가 아니라 항목별로 크게 실패하기
배치 러너는 처리할 수 있는 모든 행을 처리하고, 실패는 SKU, 프로필 버전, 이유와 함께 보고해야 합니다. 잘못된 클립 하나가 천 행짜리 작업을 중단시켜서는 안 되며, 끝의 요약이 어떤 프로필이나 입력에 주의가 필요한지 알려줍니다.
러너를 멱등하게 만들기
결정적 출력 키는 배치를 다시 실행해도 복사본을 만드는 대신 같은 산출물을 덮어쓴다는 뜻입니다. 이 특성 덕분에 러너는 예를 들어 매일 밤 새 SKU에 대해 한 번씩 실행하는 등 사람의 감시 없이 안전하게 스케줄할 수 있는 것이 됩니다.
게시 전 품질 점검
자산이 라이브로 나가기 전에 짧고 고정된 체크리스트를 실행하세요. 자동화할 수 있는 것은 자동화하고, 나머지는 명확한 책임자가 있는 리뷰 단계로 만드세요.
자동화 점검
- 길이 일치. 믹싱된 영상의 오디오 길이가 작은 허용 오차 내에서 클립 길이와 같습니다.
- 음량 일관성. 배치 전체의 오디오 레벨을 샘플링하고 이상치를 표시하세요. 정규화 방식이 다른 한 트랙은 그리드에서 유난히 눈에 띕니다.
- 루프 이음매. 루프 트랙의 이음매 구간을 점검하세요. 팝이나 레벨 점프는 점검 실패로 판정해야 합니다.
- 페이드 인/아웃 존재. 페이드 인과 페이드 아웃이 실제로 적용되었는지 확인하세요.
- 파일 무결성. 모든 출력이 디코딩되고 코덱이 스토어의 기대에 맞는지 검증하세요.
수동 점검
- 브랜드 적합성. 카테고리마다 대표 클립 하나를 들어 보세요. 생성은 비결정적이므로 보통 유효한 프로필도 때때로 브랜드에서 벗어난 트랙을 낼 수 있습니다. 다시 생성하고 해당 카테고리의 캐시를 갱신하세요.
- 텍스트 가독성. 음악이 화면 문구나 내레이션을 가리지 않는지, 특히 휴대폰 스피커에서 확인하세요.
- 시작과 끝. 몇몇 클립의 첫 초와 마지막 초를 시청하세요. 오디오가 딱딱하게 드러나는 곳이 바로 거기입니다.
문제가 생겼을 때
산출물에서 바깥으로 향해 조사하세요. 영상은 잘못됐지만 트랙이 맞다면 문제는 믹싱 단계나 매니페스트에 있습니다. 트랙이 잘못됐다면 모델을 다시 호출하기 전에 렌더링된 프롬프트와 프로필 버전을 확인하세요. 요청 자체가 실패하거나 예상치 못한 구조를 반환하면 mureka-9.5/instrumental 모델 페이지에서 현재 계약을 확인하고, 그것에 비추어 자격 증명과 페이로드를 점검하세요.
이 점검들을 별도의 감사가 아니라 배치의 일부로 실행하세요. 스스로 출력을 검증하는 파이프라인이야말로 이 전체 접근 방식을 반복 가능하게 만드는 핵심입니다.
프로필, 트랙 캐시, 점검이 자리를 잡으면 새 제품 카테고리를 추가하는 일은 새로운 생산 프로젝트가 아니라 작고 검토 가능한 변경 하나가 됩니다. 바로 그것이 BGM 레이어를 따로 구축한 이유입니다.