> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 음악 & 사운드 이펙트

> Venice의 비동기 오디오 API로 음악과 사운드 이펙트를 생성하세요: 모델을 선택하고, 비용 견적을 요청하고, 작업을 큐에 넣은 뒤 완성된 오디오를 다운로드합니다.

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

## 모델 선택

현재 모델 ID, 가격, 길이 제한, 지원 기능은 [음악 & 사운드 이펙트 모델](/models/music)에서 확인하세요.

런타임에서 모델 기능을 확인할 수도 있습니다:

```bash theme={"system"}
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`](/api-reference/endpoint/audio/quote)       | USD 기준 생성 비용 견적      |
| [`POST /audio/queue`](/api-reference/endpoint/audio/queue)       | 음악 또는 사운드 이펙트 생성 시작  |
| [`POST /audio/retrieve`](/api-reference/endpoint/audio/retrieve) | 작업 폴링 및 완성된 오디오 다운로드 |
| [`POST /audio/complete`](/api-reference/endpoint/audio/complete) | 다운로드 후 저장된 미디어 삭제    |

## 1. 가격 견적 받기

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

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

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

```json theme={"system"}
{
  "quote": 0.75
}
```

## 2. 생성 큐에 넣기

<CodeGroup>
  ```bash Music theme={"system"}
  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
    }'
  ```

  ```bash Sound effect theme={"system"}
  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
    }'
  ```
</CodeGroup>

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

```json theme={"system"}
{
  "model": "elevenlabs-music",
  "queue_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "QUEUED"
}
```

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

## 3. 폴링 및 다운로드

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

```bash theme={"system"}
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` | 생성 완료       | 해당 확장자로 바이너리 본문 저장     |

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

```json theme={"system"}
{
  "status": "PROCESSING",
  "average_execution_time": 20000,
  "execution_duration": 5200
}
```

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

## 전체 예시

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

```python theme={"system"}
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()
```

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

## 프롬프트 팁

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

## 관련 리소스

* [음악 & 사운드 이펙트 모델](/models/music)
* [Queue Audio Generation API](/api-reference/endpoint/audio/queue)
* [Retrieve Audio API](/api-reference/endpoint/audio/retrieve)