Mirelo SFX 2.0 API 사용법? 5분 만에 첫 번째 음향 효과 생성하기

TL;DR

• 무엇인가: 텍스트→음향 효과 모델로, 설명 한 줄로 1–30초 길이의 WAV(PCM 16-bit / 48 kHz / 모노)를 얻습니다. Mirelo SFX 2.0 모델 페이지 열기 에서 한 문장만 작성하면 미리 들어볼 수 있습니다. Mirelo SFX 2.0이 HiAPI에 출시되었으며 신규 사용자는 가입 시 200 크레딧을 받습니다.
• 얼마인가: 출력 초 단위로 과금되며 초당 $0.0215(43 크레딧), 최소 1초부터 시작합니다. 5초는 $0.1075, 30초는 $0.645입니다.
• 가장 빠른 호출 방법: 모델 페이지에서 설명을 입력하고 길이를 선택한 뒤 제출하면 됩니다. 제품에 연동하려면 POST /v1/tasks를 사용하고 model에 mirelo-sfx-2.0을, input에는 prompt와 duration만 넣습니다.

Mirelo SFX 2.0이란

입력은 두 필드뿐입니다: prompt와 duration. 설명은 1–2,000자이며 음원, 재질, 동작, 거리와 환경을 명확히 쓰고 어택과 테일을 덧붙입니다. duration은 1–30 사이의 정수 초이며 기본값은 5입니다. 출력은 WAV 1개로 고정되며 PCM 16-bit, 48 kHz, 모노이고 형식 옵션은 없습니다.

단일 음향 효과와 환경음만 다룹니다. 요청 한 번에 하나의 소리 이벤트를 생성하며, 노래나 보컬, 대사는 생성하지 않습니다. 편집에서 충돌 지점 하나를 채워야 할 때, 게임에 UI 피드백 음 하나가 필요할 때, 숏폼 영상에 비 오는 밤의 배경 잡음이 필요할 때 모두 이 모델의 역할입니다.

사이트 내 이 망치 타격 사례는 1초에 $0.0215입니다. 트랜지언트와 금속 잔향이 모두 이 1초 안에 담겨 있습니다.

미리 듣기: 강철 빔 위의 망치 타격, 1초 WAV

A single heavy hammer strike on a steel beam in a large empty warehouse, sharp transient, long metallic ring, close perspective.

이 프롬프트로 생성하기 → 링크는 설명만 미리 채우므로, 열린 후 duration을 1초로 설정해야 이 결과가 됩니다.

같은 모델, 같은 필드 세트로 10초 환경음 사례도 들어보세요:

미리 듣기: 비 오는 밤의 금속 지붕, 10초 WAV

온라인 체험: 4단계로 첫 소리 듣기

1. Mirelo SFX 2.0 모델 페이지를 열면 가입 시 200 크레딧을 받습니다.
2. 설명 상자에 위의 망치 타격 설명을 붙여넣거나, 원하는 소리로 바꿉니다.
3. duration을 1–3초로 설정하고 먼저 어택과 테일을 들어봅니다.
4. 제출을 누르면 플레이어에 WAV가 나오며 바로 다운로드할 수 있습니다.

3단계를 건너뛰지 마세요. 같은 설명이라도 1초와 10초에서는 전혀 다른 결과가 나옵니다. 짧게 먼저 하고 길게 하는 것이 반복 생성 비용을 아끼는 방법입니다.

API 연동: 4단계로 완료

1. 콘솔에서 API Key를 생성합니다.
2. POST https://api.hiapi.ai/v1/tasks를 호출하고 model에 mirelo-sfx-2.0을, input에 prompt와 duration을 넣습니다.
3. 반환된 taskId를 받아 callback 알림을 기다리거나 GET /v1/tasks/{taskId}를 폴링합니다.
4. status가 success가 되면 output에서 type이 audio인 항목을 찾아 그 url로 WAV를 다운로드합니다.

실행 가능한 curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mirelo-sfx-2.0",
    "input": {
      "prompt": "A single heavy hammer strike on a steel beam in a large empty warehouse, sharp transient, long metallic ring, close perspective.",
      "duration": 1
    }
  }'

응답의 작업 ID는 data.taskId에 있습니다:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

이 ID로 상태를 조회합니다:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

data.status는 queued, handling, success 또는 fail을 거칩니다. 성공 시 data.output에서 type이 audio인 항목을 찾습니다.

Python 버전: 생성, 폴링, 다운로드를 한 번에

import requests
import time

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

payload = {
    "model": "mirelo-sfx-2.0",
    "input": {
        "prompt": "A single heavy hammer strike on a steel beam in a large empty warehouse, sharp transient, long metallic ring, close perspective.",
        "duration": 1,
    },
}

task_id = requests.post(BASE, headers=HEADERS, json=payload, timeout=30).json()["data"]["taskId"]

while True:
    data = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

if data["status"] == "success":
    audio_url = next(item["url"] for item in data["output"] if item["type"] == "audio")
    with open("effect.wav", "wb") as f:
        f.write(requests.get(audio_url, timeout=60).content)
    print("saved effect.wav")
else:
    print(data.get("error"))

음향 효과 작업은 영상보다 훨씬 짧으므로 폴링 간격은 2초면 충분하며, 3초를 꽉 채울 필요가 없습니다.

설명 작성법: 다섯 가지 요소

추가 파라미터는 없으며 prompt가 곧 전부의 제어면입니다. 다음 다섯 가지에 맞춰 쓰면 한 번에 완성됩니다:

요소	무엇을 쓸까	사례의 대응 문장
음원	무엇이 소리를 내는가	a heavy hammer strike
재질	발음체의 재료	on a steel beam
동작	어떻게, 얼마나 세게 소리 나는가	single, heavy
거리와 환경	청자가 어디에 있고 공간이 얼마나 큰가	in a large empty warehouse, close perspective
어택과 테일	시작이 얼마나 빠른가, 끝이 얼마나 긴가	sharp transient, long metallic ring

확신이 없는 차원은 생략하고, 「대략」「영화 같은」 같은 형용사는 쓰지 마세요. 설명 속 구체적인 명사 하나하나가 소리에 반영됩니다. 「no music and no voices」 같은 마무리 문장은 한 줄 넣어 둘 가치가 있으며, 원하지 않는 레이어를 한 번에 배제합니다.

길이 선택법

먼저 1–3초로 음색, 어택, 테일이 맞는지 확인하고, 확정되면 duration을 목표 길이로 늘리세요. 같은 설명이라도 3초와 10초에서는 이벤트 밀도가 달라집니다. 짧은 버전으로 방향을试探하고 긴 버전으로 완성품을 얻는 편이 곧바로 30초를 돌리는 것보다 훨씬 저렴합니다.

• 충돌, UI, 탭 → 1–3초.
• 환경음, 배경 잡음, 방 분위기 → 10–30초.
• 샷 길이에 맞춰야 할 때 → 샷 초 수를 그대로 정수로 반올림해 입력하면 모델이 지정한 초 수대로 납품합니다.

출시 전 주의할 4가지

1. 콜백에 폴링 폴백을 더하세요. 요청 본문에 "callback": {"url": "https://yourapp.com/webhook", "when": "final"}를 추가하면 작업이 종료 상태에 도달할 때 알림을 받습니다. 알림이 유실될 수 있으니 정기적인 GET /v1/tasks/{taskId}도 함께 보완하세요.
2. taskId 기준으로 멱등성을 보장하세요. success와 fail 모두 종료 상태이며 같은 taskId에 대해 알림이 여러 번 올 수 있으니, 처리 전에 DB를 조회해 중복을 제거하세요.
3. 결과물 링크는 만료됩니다. output의 url은 임시 주소이므로 받는 즉시 자체 저장소로 전송하세요. 장기 CDN처럼 쓰지 마세요.
4. 설명 하나에는 이벤트 하나만. 충돌에 파편 낙하, 빗소리에 천둥소리와 개 짖는 소리까지 넣으려면 여러 요청으로 나눠 각각 생성하고 후반에 겹치는 편이 한 문장에 넣는 것보다 제어하기 쉽습니다.

자주 묻는 질문

Mirelo SFX 2.0으로 노래나 보컬을 생성할 수 있나요? 아니요. 단일 음향 효과와 환경음만 다루며 길이 상한은 30초입니다. 배경 음악은 음악 모델, 내레이션은 음성 모델을 사용하세요.

duration을 입력하지 않으면 어떻게 되나요? 5초로 생성되며 $0.1075가 차감됩니다. 다른 길이를 원하면 1–30 사이의 정수를 명시하세요.

출력을 MP3나 스테레오로 선택할 수 있나요? 아니요, WAV 1개로 고정되며 PCM 16-bit, 48 kHz, 모노입니다. 다른 형식이 필요하면 후반에서 변환하세요.

설명은 최대 얼마나 쓸 수 있나요? 2,000자로, 하나의 완전한 사운드 명세를 담기에 충분합니다.

지금 첫 번째를 실행하세요

위의 망치 타격 설명을 복사하고 Mirelo SFX 2.0 모델 페이지를 열어 duration을 1초로 설정하면 $0.0215로 완전한 충돌음을 들어볼 수 있습니다. 효과를 확인한 뒤 같은 두 필드를 위의 curl에 넣어 자체 플로우에 연동하세요. 전체 파라미터는 연동 문서에서 확인하세요.

관련 읽기: Mirelo SFX 2.0 가격 · vs ElevenLabs Sound Effects v2 · 실제 음향 효과 프롬프트 4가지