---
title: "OpenClaw에서 RunAPI로 Suno 사용하기 — 음악 API 가이드"
url: "https://runapi.ai/ko/openclaw-suno.md"
canonical: "https://runapi.ai/ko/openclaw-suno"
locale: "ko"
model: "suno"
---

# OpenClaw에서 Suno를 사용하세요.

Suno는 텍스트 프롬프트나 직접 작성한 가사로 보컬, 악기, 믹싱이 포함된 완성된 노래를 생성합니다. RunAPI를 통해 v4~v5.5 버전을 이용할 수 있으며, Suno의 공식 공개 API가 없기 때문에 RunAPI가 API 접근을 제공합니다. OpenClaw 에이전트는 채팅에 사용하는 것과 동일한 RUNAPI_API_KEY로 호출합니다.

## API example

```bash
curl -X POST https://runapi.ai/api/v1/suno/text_to_music \
  -H "Authorization: Bearer $RUNAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v5.5",
    "vocal_mode": "auto_lyrics",
    "prompt": "An upbeat indie pop track about coding late at night, warm synths and acoustic guitar",
    "vocal_gender": "female"
  }'

```

### Response

```json
{
  "task_id": "tsk_abc123",
  "status": "pending",
  "model": "suno-v5.5"
}

```

## How it works

1. **RunAPI 설정** — 환경 변수에 RUNAPI_API_KEY를 설정하세요. 채팅용으로 이미 OpenClaw에 RunAPI를 설정했다면, 동일한 key로 Suno 음악 생성도 가능합니다 — 별도 공급자 설정 불필요.
2. **text_to_music 호출** — model과 vocal_mode를 포함하여 text_to_music 엔드포인트로 POST 요청을 보내세요. AI 가사 생성에는 prompt와 함께 auto_lyrics를, 직접 작성한 가사에는 lyrics/style/title과 함께 exact_lyrics를, 보컬 없는 트랙에는 style/title과 함께 instrumental을 사용하세요.
3. **결과 가져오기** — 엔드포인트는 즉시 task_id를 반환합니다. 노래 생성은 버전에 따라 30초에서 수 분이 소요됩니다. 상태가 completed가 될 때까지 작업 상태 엔드포인트를 폴링한 후 오디오 URL을 읽으세요.

## Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `model` | `string` | 필수. suno-v4, suno-v4.5, suno-v4.5-all, suno-v4.5-plus, suno-v5, 또는 suno-v5.5. |
| `vocal_mode` | `string` | 필수. auto_lyrics(AI가 프롬프트로 가사 작성), exact_lyrics(lyrics/style/title 직접 제공), 또는 instrumental(보컬 없음, style/title 필요). |
| `prompt` | `string` | auto_lyrics 모드용 노래 설명. 장르, 분위기, 템포, 주제를 설명하세요. exact_lyrics 및 instrumental 모드에서는 사용 불가. |
| `lyrics` | `string` | 노래할 정확한 가사. exact_lyrics 모드에서 필수. auto_lyrics 및 instrumental 모드에서는 사용 불가. |
| `style` | `string` | 음악 스타일 설명 (예: lo-fi hip hop, 80s synthwave). exact_lyrics 및 instrumental 모드에서 필수. |
| `title` | `string` | 노래 제목. exact_lyrics 및 instrumental 모드에서 필수. |
| `vocal_gender` | `string` | 선택 사항. male 또는 female. |
| `negative_tags` | `string` | 선택 사항. 피하고 싶은 스타일 (예: heavy metal, screaming). |
| `duration_seconds` | `integer` | 선택 사항. 목표 재생 시간(초). |
| `persona_id` | `string` | 선택 사항. 커스텀 음성 또는 스타일 프로필의 Persona ID. |
| `persona_type` | `string` | 선택 사항. style 또는 voice. 페르소나 카테고리를 선택합니다. |
| `callback_url` | `string` | 선택 사항. 작업 완료 시 POST를 수신할 웹훅 URL. |

## FAQ

### auto_lyrics, exact_lyrics, instrumental의 차이점은 무엇인가요?

auto_lyrics는 프롬프트로 가사를 생성합니다 — 노래를 설명하면 Suno가 가사를 작성합니다. exact_lyrics는 직접 제공한 가사를 그대로 사용하며 style과 title 필드가 필요합니다. instrumental은 보컬 없이 style과 title만으로 트랙을 만듭니다.

### 어떤 Suno 버전을 사용해야 하나요?

suno-v5.5가 최신 버전으로 보컬 선명도와 믹싱이 가장 우수합니다. suno-v4와 suno-v4.5는 초안 작업에 더 저렴하고 빠릅니다. 모든 버전이 동일한 text_to_music 엔드포인트와 파라미터를 사용합니다.

### Suno 생성에 얼마나 걸리나요?

생성 시간은 버전과 노래 길이에 따라 다릅니다. 일반적으로 30초에서 2분이 소요됩니다. API는 즉시 task_id를 반환하므로 상태 엔드포인트를 폴링하거나 callback_url을 설정하여 에이전트가 블로킹되지 않도록 하세요.

### RunAPI가 공식 Suno API를 제공하나요?

Suno는 공개 API를 제공하지 않습니다. RunAPI는 다른 모든 RunAPI 모델과 동일한 API key와 작업 생명주기를 통해 Suno v4~v5.5에 프로그래밍 방식의 접근을 제공합니다. Suno 계정이나 별도 인증 정보가 필요하지 않습니다.

### 음성 성별과 스타일 가중치를 제어할 수 있나요?

네. vocal_gender를 male 또는 female로 설정하세요. negative_tags로 원하지 않는 스타일을 제외할 수 있습니다. 더 세밀한 제어를 원하면 generate_persona 엔드포인트로 페르소나를 만들고 반환된 persona_id를 persona_type을 voice 또는 style로 설정하여 전달하세요.


## Links

- [OpenClaw 설정 가이드 →](https://runapi.ai/ko/openclaw)
- [RunAPI의 Suno →](https://runapi.ai/ko/models/suno)
- [Model catalog](https://runapi.ai/ko/models)
- [API docs](https://runapi.ai/ko/docs)