---
title: "通过 RunAPI 在爱马仕 (Hermes Agent) 中使用 Suno — 音乐 API 指南"
url: "https://runapi.ai/zh-CN/hermes-suno.md"
canonical: "https://runapi.ai/zh-CN/hermes-suno"
locale: "zh-CN"
model: "suno"
---

# 在 Hermes Agent 中使用 Suno。

Suno 从文本提示词或精确歌词生成完整歌曲——人声、乐器和混音。v4 到 v5.5 各版本均可通过 RunAPI 使用，由于 Suno 没有官方公开 API，RunAPI 提供了 API 访问能力。Hermes Agent 通过 custom:runapi 提供商，使用与聊天相同的 API 密钥调用它。

## 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. **Configure RunAPI** — Set RUNAPI_API_KEY in the environment where Hermes Agent runs. If you already added RunAPI as a custom:runapi provider, the same key and base_url handle Suno music requests.
2. **Call text_to_music** — Send a POST to the text_to_music endpoint with the model and vocal_mode. Use auto_lyrics with a prompt for AI-written lyrics, exact_lyrics with lyrics/style/title for your own words, or instrumental with style/title for no vocals.
3. **Poll for the result** — The endpoint returns a task_id immediately. Song generation takes 30 seconds to several minutes depending on version. Poll the task status endpoint until the status is completed, then read the output audio URL.

## Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `model` | `string` | Required. suno-v4, suno-v4.5, suno-v4.5-all, suno-v4.5-plus, suno-v5, or suno-v5.5. |
| `vocal_mode` | `string` | Required. auto_lyrics (AI writes lyrics from prompt), exact_lyrics (you provide lyrics/style/title), or instrumental (no vocals, requires style/title). |
| `prompt` | `string` | Song brief for auto_lyrics mode. Describe genre, mood, tempo, and subject. Forbidden in exact_lyrics and instrumental modes. |
| `lyrics` | `string` | Exact lyrics to sing. Required for exact_lyrics mode. Forbidden in auto_lyrics and instrumental modes. |
| `style` | `string` | Music style description, e.g. lo-fi hip hop, 80s synthwave. Required for exact_lyrics and instrumental modes. |
| `title` | `string` | Song title. Required for exact_lyrics and instrumental modes. |
| `vocal_gender` | `string` | Optional. male or female. |
| `negative_tags` | `string` | Optional. Styles to avoid, e.g. heavy metal, screaming. |
| `duration_seconds` | `integer` | Optional. Target duration in seconds. |
| `persona_id` | `string` | Optional. Persona ID for custom voice or style profiles. |
| `persona_type` | `string` | Optional. style or voice. Selects the persona category. |
| `callback_url` | `string` | Optional. Webhook URL that receives a POST when the task completes. |

## FAQ

### How do I write better Suno prompts to get the genre and style I want?

Be specific about genre, mood, tempo, and instrumentation in your prompt. For example, "upbeat 120 BPM indie pop with acoustic guitar and warm synths" works better than "happy song." Use negative_tags to exclude unwanted elements. Meta tags in the prompt help Suno understand song structure.

### How do I configure RunAPI as a custom provider in Hermes Agent for Suno?

Add a custom:runapi provider in the Hermes Agent config with base_url set to https://runapi.ai/v1 and api_key reading from RUNAPI_API_KEY. The same provider handles chat, image, video, and music endpoints -- no separate config for Suno.

### Can I extend a Suno song beyond the initial clip length?

Yes. Use the extend_music endpoint to continue a song from a specific timestamp. You can chain multiple extensions to build longer tracks. RunAPI also offers cover_audio to restyle existing tracks and create_mashup to combine elements from multiple songs.

### Can I generate instrumental-only tracks without vocals?

Yes. Set vocal_mode to instrumental and provide style and title fields. The prompt and lyrics fields must be omitted in instrumental mode. The API enforces these cross-field rules and returns a validation error if conflicting fields are sent.

### What other Suno endpoints are available beyond text_to_music?

RunAPI exposes cover_audio (restyle an existing track), extend_music (continue a song from a timestamp), create_mashup (combine elements from multiple tracks), text_to_sound (sound effects), and utility endpoints like generate_lyrics, generate_persona, and separate_audio_stems. All share the same API key and task lifecycle.

### How does Hermes Agent handle Suno's custom lyrics mode?

Set the is_custom parameter to true and provide your exact lyrics in the prompt field when calling the Suno endpoint through Hermes Agent. The custom:runapi provider passes all parameters to Suno, which generates the song using your lyrics.

### Can Hermes Agent chain Suno with video models for complete content creation?

Yes. Hermes Agent can generate video with Kling or Veo 3, then create a matching soundtrack with Suno, combining both outputs into a complete audiovisual package within one workflow.


## Links

- [Hermes Agent 配置指南 →](https://runapi.ai/zh-CN/hermes-agent)
- [Suno 模型 →](https://runapi.ai/zh-CN/models/suno)
- [Model catalog](https://runapi.ai/zh-CN/models)
- [API docs](https://runapi.ai/zh-CN/docs)