Music & Sound Effects | Venice API Docs

음악과 사운드 이펙트 생성은 비동기 방식입니다. 모델을 선택하고, 가격 견적을 요청하고, 생성 작업을 큐에 넣은 다음, Venice가 완성된 오디오 파일을 반환할 때까지 폴링하세요.

모델 선택

현재 모델 ID, 가격, 길이 제한, 지원 기능은 음악 & 사운드 이펙트 모델에서 확인하세요. 런타임에서 모델 기능을 확인할 수도 있습니다:

curl "https://api.venice.ai/api/v1/models?type=music" \
  -H "Authorization: Bearer $VENICE_API_KEY"

duration_seconds, lyrics_prompt, force_instrumental, loop 같은 선택적 필드를 설정하기 전에 각 모델의 메타데이터를 확인하세요. 지원되지 않는 필드는 HTTP 400 응답을 유발합니다.

생성 흐름

엔드포인트	용도
`POST /audio/quote`	USD 기준 생성 비용 견적
`POST /audio/queue`	음악 또는 사운드 이펙트 생성 시작
`POST /audio/retrieve`	작업 폴링 및 완성된 오디오 다운로드
`POST /audio/complete`	다운로드 후 저장된 미디어 삭제

1. 가격 견적 받기

미디어를 생성하기 전에 요청에 대한 견적을 받으세요. 큐 엔드포인트로 보낼 모델과 길이를 동일하게 포함하세요.

curl https://api.venice.ai/api/v1/audio/quote \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-music",
    "duration_seconds": 30
  }'

응답에는 USD 기준 예상 비용이 포함됩니다:

{
  "quote": 0.75
}

2. 생성 큐에 넣기

curl https://api.venice.ai/api/v1/audio/queue \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-music",
    "prompt": "Warm cinematic strings with a gentle piano melody, hopeful and spacious",
    "duration_seconds": 30,
    "force_instrumental": true
  }'

curl https://api.venice.ai/api/v1/audio/queue \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-sound-effects-v2",
    "prompt": "Ocean waves rolling onto a pebble beach at night",
    "duration_seconds": 10
  }'

요청이 성공하면 모델과 큐 ID가 반환됩니다:

{
  "model": "elevenlabs-music",
  "queue_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "QUEUED"
}

model과 queue_id를 모두 저장하세요. retrieve 및 complete 엔드포인트에서 필요합니다.

3. 폴링 및 다운로드

큐 응답에서 받은 값으로 /audio/retrieve를 호출하세요:

curl https://api.venice.ai/api/v1/audio/retrieve \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-music",
    "queue_id": "123e4567-e89b-12d3-a456-426614174000"
  }' \
  --output response.bin

응답의 Content-Type을 확인하세요:

Content-Type	의미	조치
`application/json`	생성이 아직 처리 중	타이밍 필드를 읽고 기다린 뒤 다시 폴링
`audio/mpeg`, `audio/wav`, `audio/flac`	생성 완료	해당 확장자로 바이너리 본문 저장

처리 중 응답은 다음과 같은 형태입니다:

{
  "status": "PROCESSING",
  "average_execution_time": 20000,
  "execution_duration": 5200
}

두 타이밍 값은 모두 밀리초 단위입니다.

전체 예시

이 Python 예제는 연주 음악을 큐에 넣고, 5초마다 폴링하며, 콘텐츠 유형에 맞는 확장자로 결과를 저장합니다.

import os
import time
from pathlib import Path

import requests

BASE_URL = "https://api.venice.ai/api/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
    "Content-Type": "application/json",
}

generation = {
    "model": "elevenlabs-music",
    "prompt": "Warm cinematic strings with a gentle piano melody, hopeful and spacious",
    "duration_seconds": 30,
    "force_instrumental": True,
}

quote = requests.post(f"{BASE_URL}/audio/quote", json={
    "model": generation["model"],
    "duration_seconds": generation["duration_seconds"],
})
quote.raise_for_status()
print(f"Estimated cost: ${quote.json()['quote']:.2f}")

queued = requests.post(f"{BASE_URL}/audio/queue", headers=HEADERS, json=generation)
queued.raise_for_status()
job = queued.json()

content_type_to_extension = {
    "audio/mpeg": ".mp3",
    "audio/wav": ".wav",
    "audio/flac": ".flac",
}

while True:
    result = requests.post(
        f"{BASE_URL}/audio/retrieve",
        headers=HEADERS,
        json={"model": job["model"], "queue_id": job["queue_id"]},
    )
    result.raise_for_status()
    content_type = result.headers.get("Content-Type", "").split(";")[0]

    if content_type in content_type_to_extension:
        output = Path("generated-audio" + content_type_to_extension[content_type])
        output.write_bytes(result.content)
        print(f"Saved {output}")
        break

    status = result.json()
    print(f"Status: {status['status']}")
    time.sleep(5)

requests.post(
    f"{BASE_URL}/audio/complete",
    headers=HEADERS,
    json={"model": job["model"], "queue_id": job["queue_id"]},
).raise_for_status()

quote 엔드포인트는 인증이 필요하지 않지만, queue, retrieve, complete 요청에는 인증이 필요합니다.

프롬프트 팁

음악의 경우 장르, 악기, 분위기, 템포, 구조, 그리고 보컬 여부를 설명하세요.
사운드 이펙트의 경우 음원, 환경, 강도, 타이밍, 시점을 설명하세요.
lyrics_prompt는 선택한 모델이 가사를 지원할 때만 사용하세요.
force_instrumental이나 loop는 모델 메타데이터에서 지원한다고 표시된 경우에만 사용하세요.

문서

시작하기

텍스트 및 채팅

이미지, 비디오 및 오디오

검색 및 RAG

에이전트 및 통합

코딩 도구

에이전트 도구

SDK 및 프레임워크

음악 & 사운드 이펙트

모델 선택

생성 흐름

1. 가격 견적 받기

2. 생성 큐에 넣기

3. 폴링 및 다운로드

전체 예시

프롬프트 팁

관련 리소스

​모델 선택

​생성 흐름

​1. 가격 견적 받기

​2. 생성 큐에 넣기

​3. 폴링 및 다운로드

​전체 예시

​프롬프트 팁

​관련 리소스

모델 선택

생성 흐름

1. 가격 견적 받기

2. 생성 큐에 넣기

3. 폴링 및 다운로드

전체 예시

프롬프트 팁

관련 리소스