Suno检查中

suno-single-v4.5

suno-single-v4-5

文生音乐输出: 音乐与音频输入: 文本

正在加载价格…

官方原价 · 未验证

在 Playground 中试用获取 API Key

参数

必填

Descriptiondescription: string

Describe the music style/mood/scene in plain text, up to 400 chars 1–400 chars

常用参数

Instrumental Onlymake_instrumental: string

Generate instrumental music without vocals; pass string "true"/"false"

高级参数 (1)

Song Title (optional)title: string

Song title; if empty, Suno will auto-generate one based on content ≤ 80 chars

请求预览

{
  "model": "suno-single-v4-5",
  "input": {
    "make_instrumental": "false"
  }
}

网页 Playground 使用你的登录会话发送此请求体。在代码中请使用 API Key 发送相同内容。

预计费用

正在加载价格…

任务接收时预留额度，仅成功后扣费。失败任务释放预留额度；结果未确认时会保留额度，直到核实。

模型能力

Input a single sentence describing the song (style/mood/scene). The model automatically generates two alternative complete tracks. Compared to previous versions, v4.5 significantly expands the range of supported music styles and intelligently handles complex style mashups. Vocal expression is fuller, covering emotional range from whispers to powerful hooks. Low cost per generation, suitable for batch production.

Idea-to-SongExtensive Style SupportIntelligent Style MashupCost-Effective

输入参数

仅列出此模型接受的字段。必填字段必须提供。

字段	类型	必填	默认值	可选值与约束
`title` Song Title (optional)	`string`	可选	—	Song title; if empty, Suno will auto-generate one based on content ≤ 80 chars
`description` Description	`string`	必填	—	Describe the music style/mood/scene in plain text, up to 400 chars 1–400 chars
`make_instrumental` Instrumental Only	`string`	可选	`"false"`	Generate instrumental music without vocals; pass string "true"/"false" 可选值: `"false"`, `"true"`

限制与行为

仅支持异步：先提交任务，再轮询结果。
title: ≤ 80 chars
description: 1–400 chars

端点

所有模型共用一个异步任务 API，通过 slug 选择此模型。

提交

POST https://api.hermes-ai.net/api/v1/jobs

{
  "model": "suno-single-v4-5",
  "input": {
    "description": "Warm acoustic folk song about a morning walk"
  }
}

然后轮询 GET /api/v1/jobs/{id} 直到状态为终态。

身份验证

提交需要带 jobs:create 权限的 API Key，轮询需要 jobs:read。

请求头	值	说明
`Authorization`	`Bearer <API key>`	也可以通过 x-api-key 发送密钥。
`Content-Type`	`application/json`
`Idempotency-Key`	`<unique string ≤128>`	必填。仅在重试完全相同的请求时复用。

请求体

字段	类型	必填	说明
`model`	`string`	必填	目录中的模型 slug。
`input`	`object`	必填	模型输入 schema 中的字段。
`expectedPriceMicros`	`integer`	可选	你向用户展示的价格。不一致时在扣费前返回 409 PRICE_CHANGED。

input 字段

未知字段会被拒绝并返回 INVALID_MODEL_INPUT。

字段	类型	必填	默认值	可选值与约束
`title` Song Title (optional)	`string`	可选	—	Song title; if empty, Suno will auto-generate one based on content ≤ 80 chars
`description` Description	`string`	必填	—	Describe the music style/mood/scene in plain text, up to 400 chars 1–400 chars
`make_instrumental` Instrumental Only	`string`	可选	`"false"`	Generate instrumental music without vocals; pass string "true"/"false" 可选值: `"false"`, `"true"`

响应

新任务返回 202，Idempotency-Key 重放命中时返回 200。GET /api/v1/jobs/{id} 返回相同结构（不含 replayed）。

字段	类型	说明
`id`	`string`	Hermes AI 任务 ID，用于轮询。
`model`	`string`	模型 slug。
`status`	`string`	参见任务状态。
`errorCode`	`string \| null`	任务失败或需要核对时设置。
`priceMicros`	`integer`	接收时锁定的报价，美元微单位。
`currency`	`"USD"`
`createdAt / updatedAt`	`string`	ISO 8601 时间戳。
`assets[]`	`array`	{ id, type, url?, text? }。url 为同源 /api/v1/results/<uuid> 链接。
`replayed`	`boolean`	仅提交时返回。幂等重试命中时为 true。

任务状态

状态	终态	含义
`queued`	否	已接收，等待执行。
`submitting`	否	正在提交给模型提供方。
`running`	否	模型生成中。
`succeeded`	是	已完成，结果位于 assets。
`failed`	是	未产生结果，预留额度已释放。
`reconciliation_required`	是	结果正在核实。请保留任务 ID，不要自动重新提交。

错误

错误响应体为 { code, error }，请根据 code 处理。

HTTP	代码	含义与处理方式
`401`	`AUTH_REQUIRED`	缺少或无效的 API Key 或会话。
`403`	`INSUFFICIENT_SCOPE`	API Key 缺少此端点所需的权限。
`403`	`PERMISSION_DENIED`	此凭据无权执行该操作。
`429`	`API_KEY_RATE_LIMITED`	已达到 API Key 的频率限制，请遵循 Retry-After。
`429`	`API_KEY_USAGE_EXCEEDED`	API Key 已达到使用上限，请创建新密钥。
`400`	`INVALID_REQUEST`	请求体不是 JSON 对象，或缺少必需值。
`400`	`INVALID_IDEMPOTENCY_KEY`	Idempotency-Key 必须是 1–128 个可打印 ASCII 字符。
`400`	`INVALID_MODEL_INPUT`	input 与模型 schema 不匹配（未知字段、缺少必填字段或值无效）。
`400 / 413`	`INPUT_TOO_LARGE`	请求体超过 256 KB。请先上传媒体并发送媒体引用。
`404`	`REQUEST_NOT_FOUND`	No chat request with this ID belongs to your account.
`404`	`MODEL_NOT_FOUND`	没有此 slug 对应的模型。
`404`	`JOB_NOT_FOUND`	你的账户中没有此 ID 的任务。
`409`	`IDEMPOTENCY_CONFLICT`	此 Idempotency-Key 已用于不同的输入。新请求请使用新密钥。
`409`	`PRICE_CHANGED`	价格与 expectedPriceMicros 不一致。请重新获取价格并确认。
`409`	`MODEL_PRICE_UNAVAILABLE`	此模型尚未配置价格，暂不可运行。
`409`	`PAYMENT_REVIEW_REQUIRED`	退款后余额不足。请联系支持或补足余额后再提交任务。
`409`	`INSUFFICIENT_CREDITS`	可用额度不足以支付此任务。
`429`	`RATE_LIMITED`	每分钟提交次数过多，请稍后重试。
`429`	`CONCURRENCY_LIMITED`	未完成任务过多，请等待任务完成。
`503`	`EXECUTION_UNAVAILABLE`	此模型当前未配置执行能力。
`429`	`UPSTREAM_RATE_LIMITED`	The model provider is rate limiting chat requests. Retry with backoff; nothing was charged.
`502`	`UPSTREAM_ERROR`	The model provider failed the chat request. Nothing was charged; retry later.
`503`	`PLATFORM_BUDGET_EXCEEDED`	此模型暂时不可用，请稍后重试。
`503`	`EXECUTION_TEMPORARILY_UNAVAILABLE`	执行暂时不可用，请使用相同的 Idempotency-Key 重试。
`503`	`AUTH_UNAVAILABLE`	身份验证暂时不可用，请稍后重试。
`503`	`API_UNAVAILABLE`	API 暂时不可用，请稍后重试。

完整 API 指南 · OpenAPI 3.1

Hermes AI 价格

正在加载价格…

无法加载实时价格，请刷新重试。

官方原价

模型厂商标准 API 美元原价，未应用渠道折扣。计费单位和规格以官方来源为准。

尚未核实此模型的官方原价。

影响成本的因素

分辨率、时长和输出数量可能影响报价。提交前请查看价格表和试验场报价。

· 仅对成功任务扣费。失败任务释放预留额度；结果尚未确认的任务会保留额度，直到结果核实。
· 使用相同幂等密钥重试不会重复扣费。
· 发送 expectedPriceMicros：若展示后价格发生变化，任务会以 PRICE_CHANGED 被拒绝。

费用估算

请在试验场选择规格，查看本次任务报价。

// 账单

计费方式

任务使用预付额度。可在账单页面充值，付款确认后余额更新。

发生时机	影响
任务已接收	从余额中预留本次报价金额。
任务成功	从预留额度中扣费一次。
任务失败	预留额度退回可用余额。

结果尚未确认的任务会保留预留额度，直到结果核实。如需帮助，请保留任务 ID 并联系支持。

付款退款会同步更新余额，并显示在账单页面的交易记录中。

最小请求

仅包含必填字段，由此模型的 schema 生成。请在环境变量中设置 HERMES_API_KEY。

# 1. Submit the task (asynchronous; returns 202 with a task id)
curl -X POST https://api.hermes-ai.net/api/v1/jobs \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "model": "suno-single-v4-5",
  "input": {
    "description": "Warm acoustic folk song about a morning walk"
  }
}'

# 2. Poll until status is succeeded, failed or reconciliation_required
curl https://api.hermes-ai.net/api/v1/jobs/TASK_ID \
  -H "Authorization: Bearer $HERMES_API_KEY"

包含默认值

相同请求，并写出每个可选参数的默认值，便于调整。

# 1. Submit the task (asynchronous; returns 202 with a task id)
curl -X POST https://api.hermes-ai.net/api/v1/jobs \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "model": "suno-single-v4-5",
  "input": {
    "description": "Warm acoustic folk song about a morning walk",
    "make_instrumental": "false"
  }
}'

# 2. Poll until status is succeeded, failed or reconciliation_required
curl https://api.hermes-ai.net/api/v1/jobs/TASK_ID \
  -H "Authorization: Bearer $HERMES_API_KEY"