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

# Hermes Agent에서 Suno를 사용하세요.

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

## 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 설정** — Hermes Agent가 실행되는 환경에 RUNAPI_API_KEY를 설정하세요. 이미 RunAPI를 custom:runapi 공급자로 추가했다면 동일한 key와 base_url로 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만으로 트랙을 만듭니다.

### Hermes Agent에서 Suno용으로 RunAPI를 커스텀 공급자로 설정하는 방법은?

Hermes Agent 설정에서 base_url을 https://runapi.ai/v1으로, api_key를 RUNAPI_API_KEY에서 읽도록 custom:runapi 공급자를 추가하세요. 동일한 공급자가 채팅, 이미지, 영상, 음악 엔드포인트를 모두 처리하며 Suno를 위한 별도 설정이 필요하지 않습니다.

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

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

### 보컬 없이 악기만으로 트랙을 생성할 수 있나요?

네. vocal_mode를 instrumental로 설정하고 style과 title 필드를 제공하세요. instrumental 모드에서는 prompt와 lyrics 필드를 생략해야 합니다. API가 이 크로스 필드 규칙을 강제하며 충돌하는 필드가 전송되면 유효성 검사 오류를 반환합니다.

### text_to_music 외에 사용 가능한 다른 Suno 엔드포인트는 무엇인가요?

RunAPI는 cover_audio(기존 트랙 스타일 변경), extend_music(타임스탬프부터 노래 계속), create_mashup(여러 트랙 요소 결합), text_to_sound(효과음), 그리고 generate_lyrics, generate_persona, separate_audio_stems 등 유틸리티 엔드포인트를 제공합니다. 모두 동일한 API key와 작업 생명주기를 공유합니다.


## Links

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