Suno

Suno AI 音乐生成。创作高质量歌曲，支持歌词、纯音乐和自定义风格。每次生成会产出多个音频变体。

模型

模型名称	说明
`suno-v5_5`	Suno V5.5 - 定制化模型，个性化音乐品味
`suno-v5`	Suno V5 - 卓越表现力，更快生成速度

定价

按次计费：

模型	积分	价格
`suno-v5_5`	24 积分	$0.12
`suno-v5`	24 积分	$0.12

每次生成会产出多个音频。

创建任务

curl -X POST https://api.aivideoapi.ai/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v5_5",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "一首轻柔舒缓的钢琴曲",
      "custom_mode": false,
      "instrumental": true
    }
  }'

请求体

字段	类型	必填	说明
`model`	string	是	`suno-v5_5` 或 `suno-v5`
`input`	object	是	生成参数，见下方
`callback_url`	string	否	任务完成/失败时接收通知的 URL

Input 参数

参数取决于是否启用自定义模式。

非自定义模式（简单）

字段	类型	必填	说明
`prompt`	string	是	音频内容描述（最长 500 字符）
`custom_mode`	boolean	否	设为 `false` 或省略。默认 `false`
`instrumental`	boolean	否	设为 `true` 则生成纯音乐。默认 `false`

自定义模式

字段	类型	必填	说明
`prompt`	string	条件必填	歌词文本（最长 3000 字符）。`instrumental` 为 `false` 时必填
`custom_mode`	boolean	是	必须为 `true`
`instrumental`	boolean	否	设为 `true` 则生成纯音乐。默认 `false`
`title`	string	是	歌曲标题（最长 80 字符）
`style`	string	是	音乐风格/情绪（最长 200 字符）
`negative_tags`	string	否	排除的风格（最长 200 字符）
`vocal_gender`	string	否	人声偏好：`m`（男声）或 `f`（女声）
`persona_id`	string	否	自定义声音风格 ID
`style_weight`	number	否	风格贴合度（0-1）
`weirdness_constraint`	number	否	创意偏差控制（0-1）
`audio_weight`	number	否	音频特征平衡（0-1）

示例：简单生成

curl -X POST https://api.aivideoapi.ai/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v5",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "一首节奏强烈的电子舞曲，带有重低音"
    }
  }'

示例：自定义纯音乐

curl -X POST https://api.aivideoapi.ai/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v5_5",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "custom_mode": true,
      "instrumental": true,
      "title": "静谧钢琴冥想",
      "style": "古典, 氛围, 钢琴",
      "negative_tags": "重金属, 鼓点"
    }
  }'

示例：自定义歌词歌曲

curl -X POST https://api.aivideoapi.ai/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v5_5",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "custom_mode": true,
      "instrumental": false,
      "title": "夏日晚风",
      "style": "流行, 独立",
      "vocal_gender": "f",
      "prompt": "[Verse]\n走在空无一人的街\n城市灯火映在脚边\n每颗星星都在闪耀\n迷失在这夏日夜晚\n\n[Chorus]\n夏日晚风轻轻吹\n霓虹灯下我们起舞"
    }
  }'

响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

查询任务

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

状态变化：pending -> processing -> completed 或 failed。

已完成

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "model": "suno-v5_5",
  "created_at": 1775383908,
  "completed_at": 1775384028,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/audio/2026/04/05/track1.mp3",
      "https://file.aivideoapi.ai/audio/2026/04/05/track2.mp3"
    ],
    "metadata": {
      "tracks": [
        {
          "id": "track-uuid-1",
          "title": "夏日晚风",
          "tags": "流行, 独立",
          "duration": 198.44,
          "image_url": "https://example.com/cover1.jpeg",
          "prompt": "[Verse]\n走在空无一人的街..."
        },
        {
          "id": "track-uuid-2",
          "title": "夏日晚风",
          "tags": "流行, 独立",
          "duration": 201.12,
          "image_url": "https://example.com/cover2.jpeg",
          "prompt": "[Verse]\n走在空无一人的街..."
        }
      ]
    }
  }
}

音频 URL 24 小时内有效。每次生成通常会产出 2 个音轨变体。

失败

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "failed",
  "model": "suno-v5_5",
  "created_at": 1775383908,
  "error": {
    "code": "upstream_error",
    "message": "Music generation failed"
  }
}

任务失败时，预扣积分会自动退还。

回调通知

创建任务时传入 callback_url，任务完成或失败时系统会自动向该 URL 发送 POST 请求，格式与查询任务响应一致。

常见错误码

请求失败时，API 返回 JSON 格式的错误响应：

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

错误码一览

HTTP 状态码	错误码	类型	说明
400	`invalid_request`	invalid_request_error	缺少必填参数或参数无效
401	`invalid_api_key`	authentication_error	API Key 无效、已禁用或已删除
402	`insufficient_credits`	billing_error	积分余额不足，请充值
403	`ip_not_allowed`	permission_error	请求 IP 不在 Key 的白名单中
404	`model_not_found`	invalid_request_error	模型不存在或已停用
404	`task_not_found`	invalid_request_error	任务 ID 不存在
429	`rate_limit_exceeded`	rate_limit_error	请求过于频繁，请降低频率
429	`spend_limit_exceeded`	billing_error	达到 Key 的消费限额（每小时/每天/总量）
500	`internal_error`	api_error	服务器内部错误
503	`upstream_error`	upstream_error	上游 AI 服务返回错误

常见场景

invalid_request (400)

缺少必填字段或参数格式错误时返回。

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

积分不足。可通过 GET /v1/credits 查询余额，前往 Dashboard > Billing 充值。

invalid_api_key (401)

可能原因：

Key 不以 sk- 开头
Key 已被禁用或删除
用户账户已被封禁

upstream_error (503)

上游 AI 服务返回错误，可能原因：

输入内容包含敏感或违规信息
上游服务暂时不可用
请求参数不被上游支持

因上游错误导致任务失败时，预扣积分会自动退还。