ElevenLabs Sound Effects v2 API: 음향 효과 생성 및 다운로드

TL;DR

• ElevenLabs Sound Effects v2는 텍스트 설명을 하나의 MP3 음향 효과로 변환합니다. 모델 페이지 열기에서 기존 사례를 미리 들어볼 수 있습니다.
• 요청한 길이에 따라 과금되며, 초당 $0.0029입니다. 2초는 $0.0058이며, 가격은 2026년 10월 25일에 확인했습니다. 가격 보기.
• HiAPI /v1/tasks 인터페이스로 작업을 제출해 taskId를 받은 뒤 결과를 조회합니다.

Python 예제를 실행하기 전에 동일한 Python 환경에서 python -m pip install requests를 실행하세요.

먼저 2초 사례를 들어보기

모델 페이지에 이미 있는 영화 같은 저음 임팩트 사례이며, 아래에 전체 프롬프트와 오디오를 유지합니다.

Spacious cinematic braam with a deep sub-bass impact, metallic shimmer and a short reverb tail, suitable for a high-impact movie trailer moment.

전체 음향 효과 듣기

이 프롬프트로 생성 →

elevenlabs/sound-effects-v2, 2초, prompt_influence: 0.3, loop: false, MP3, 현재 가격 기준 $0.0058. 미리 채워진 링크를 열면 길이와 제어 항목을 별도로 설정합니다.

파라미터 입력 방법

필드	필수	값 및 설명
model	예	elevenlabs/sound-effects-v2, 요청 본문 최상위에 배치
input.prompt	예	1–450자, 소리, 재질, 동작 및 공간을 설명
input.duration_seconds	예	0.5–22초, 소수 지원, 반드시 명시적으로 입력
input.prompt_influence	아니요	0–1, 기본값 0.3
input.loop	아니요	불리언 값, 기본값 false

한 번에 44.1 kHz, 128 kbps MP3 하나를 반환합니다. loop는 시작과 끝을 최대한 이어지게 하는 데 사용되며 오디오를 연장하지는 않습니다. 긴 배경음은 재생 측에서 반복합니다.

curl: 첫 번째 음향 효과 제출

예제를 실행하면 실제 작업이 생성되고 길이에 따라 과금됩니다. 키를 서버 환경 변수 HIAPI_API_KEY에 넣으세요. 동일한 비즈니스 요청의 재시도는 멱등성 키를 재사용하고, 새로운 음향 효과 요청에는 새 키를 사용합니다.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sfx-example-001" \
  -d '
{
  "model": "elevenlabs/sound-effects-v2",
  "input": {
    "prompt": "Spacious cinematic braam with a deep sub-bass impact, metallic shimmer and a short reverb tail, suitable for a high-impact movie trailer moment.",
    "duration_seconds": 2,
    "prompt_influence": 0.3,
    "loop": false
  }
}'

생성 응답의 data.taskId에서 작업 ID를 가져온 뒤 GET /v1/tasks/<taskId>로 조회합니다.

Python: 제출, 대기 및 저장

requests를 설치한 후 아래 예제를 실행하세요. success와 fail만을 종료 상태로 간주하며, queued, handling, archiving은 모두 계속 기다려야 합니다.

import json
import os
import time
from pathlib import Path
import requests

api = "https://api.hiapi.ai"
key = os.environ.get("HIAPI_API_KEY", "")
if not key or any(ord(c) < 33 or ord(c) > 126 for c in key) or any(c in key for c in (chr(34), chr(39))):
    raise SystemExit("Check the key environment variable; do not print its value")
headers = {"Authorization": f"Bearer {key}"}
payload = json.loads(r'''
{
  "model": "elevenlabs/sound-effects-v2",
  "input": {
    "prompt": "Spacious cinematic braam with a deep sub-bass impact, metallic shimmer and a short reverb tail, suitable for a high-impact movie trailer moment.",
    "duration_seconds": 2,
    "prompt_influence": 0.3,
    "loop": false
  }
}
''')
response = requests.post(
    f"{api}/v1/tasks", json=payload,
    headers={**headers, "Idempotency-Key": "sfx-example-001"}, timeout=30,
)
response.raise_for_status()
task_id = response.json()["data"]["taskId"]
Path("task-id.txt").write_text(task_id, encoding="utf-8")
print("Task ID saved to task-id.txt:", task_id)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(f"{api}/v1/tasks/{task_id}", headers=headers, timeout=30)
    response.raise_for_status()
    task = response.json()["data"]
    if task["status"] == "fail":
        raise RuntimeError(task.get("error", "Task failed"))
    if task["status"] == "success":
        audio = next(item for item in task["output"] if item.get("type") == "audio")
        result = requests.get(audio["url"], timeout=120)
        result.raise_for_status()
        Path("effect.mp3").write_bytes(result.content)
        print("Saved effect.mp3")
        break
    time.sleep(4)
else:
    raise TimeoutError(f"Keep this taskId for later lookup: {task_id}")

출시 전 세 가지 점검

1. 실패와 타임아웃. HTTP 상태와 작업 error를 확인하세요. 예제では 대기 시간 초과 후 taskId를 유지하고 이후 계속 조회하여 중복 제출을 피합니다.
2. 파라미터 오류. 400 INVALID_REQUEST일 때 필수 길이, 숫자 범위 및 필드 유형을 확인하세요. 그대로 재시도하지 마세요. 실패한 작업의 선차감 금액은 환불됩니다.
3. 결과 저장. 성공 후 오디오 URL을 읽고 즉시 저장하세요. 배치 작업의 경우 callback.url을 구성하여 종료 상태 알림을 받을 수도 있습니다.

자주 묻는 질문

얼마나 긴 음향 효과를 생성할 수 있나요?

매번 0.5–22초이며 소수 초를 지원하고 duration_seconds는 필수입니다.

loop가 음향 효과를 자동으로 연장하나요?

아니요. 시작과 끝의 연결을 개선하는 데 사용되며, 길이는 여전히 duration_seconds로 결정됩니다.

2초 음향 효과는 얼마인가요?

초당 $0.0029로 계산하여 2초는 $0.0058입니다. 실패한 작업의 선차감 금액은 환불됩니다.

언제 오디오를 다운로드할 수 있나요?

status가 success가 될 때까지 기다린 후 output에서 type이 audio인 항목을 읽으세요. archiving 단계에서는 계속 기다리세요.

계속 연동하기

• 전체 모델 문서
• 작업 상태와 콜백
• 키 오류 해결
• 사례 프롬프트를 복사하여 모델 페이지에서 음향 효과 제작하기