增加人声

增加人声

curl --request POST \
  --url https://apistable.com/api/v1/tasks/create_task \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "suno_add_vocals",
  "input": {
    "upload_url": "https://example.com/instrumental.wav",
    "title": "New vocals",
    "style": "Soul",
    "negative_tags": "Distortion",
    "lyrics": "[Verse] A new day"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'suno_add_vocals',
    input: {
      upload_url: 'https://example.com/instrumental.wav',
      title: 'New vocals',
      style: 'Soul',
      negative_tags: 'Distortion',
      lyrics: '[Verse] A new day'
    }
  })
};

fetch('https://apistable.com/api/v1/tasks/create_task', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://apistable.com/api/v1/tasks/create_task"

payload = {
    "model": "suno_add_vocals",
    "input": {
        "upload_url": "https://example.com/instrumental.wav",
        "title": "New vocals",
        "style": "Soul",
        "negative_tags": "Distortion",
        "lyrics": "[Verse] A new day"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "<string>"
  }
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

POST

api

tasks

create_task

增加人声

curl --request POST \
  --url https://apistable.com/api/v1/tasks/create_task \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "suno_add_vocals",
  "input": {
    "upload_url": "https://example.com/instrumental.wav",
    "title": "New vocals",
    "style": "Soul",
    "negative_tags": "Distortion",
    "lyrics": "[Verse] A new day"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'suno_add_vocals',
    input: {
      upload_url: 'https://example.com/instrumental.wav',
      title: 'New vocals',
      style: 'Soul',
      negative_tags: 'Distortion',
      lyrics: '[Verse] A new day'
    }
  })
};

fetch('https://apistable.com/api/v1/tasks/create_task', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://apistable.com/api/v1/tasks/create_task"

payload = {
    "model": "suno_add_vocals",
    "input": {
        "upload_url": "https://example.com/instrumental.wav",
        "title": "New vocals",
        "style": "Soul",
        "negative_tags": "Distortion",
        "lyrics": "[Verse] A new day"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "<string>"
  }
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

能力按服务端配置逐项启用。未启用操作返回 503 且不创建任务；音乐积分扣除当前未启用。

调用步骤

提供伴奏 URL 和歌词，给已有音乐增加演唱。

1. 按下方示例准备输入，将占位地址和 ID 换成你有权使用的资源。
1. 将 model 设为 suno_add_vocals，参数放在 input 内。提交一次并保存返回的 task_id。
1. 查询已保存的任务，或接收回调。任务仍在处理中时继续等待，不重新提交同一操作。
从 result.data.data 读取作品。每首歌曲都有独立的本站 id，后续任务可将其作为 audio_id。

创建任务

将model和input发送到统一任务入口；可在顶层传公开HTTPS callback_url。资源ID均为本账户的本站ID。当前音乐积分扣除未启用。

{
  "model": "suno_add_vocals",
  "input": {
    "upload_url": "https://example.com/instrumental.wav",
    "title": "New vocals",
    "style": "Soul",
    "negative_tags": "Distortion",
    "lyrics": "[Verse] A new day"
  }
}

受理响应

HTTP 200仅表示受理。查询GET /api/v1/tasks/{task_id}，直到data.status为succeeded或failed。成功后读取data.result；失败原因位于data.message。

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "YOUR_TASK_ID"
  }
}

参数速查

字段	类型	必填	说明与限制
vocal_gender	string	否 / 依条件	m 或 f，表示人声倾向，不保证特定声音身份；生成时仅限自定义模式。 values: m, f
style_weight	number	否 / 依条件	风格影响程度，0–1，最多两位小数；生成时仅限自定义模式。 min: 0; max: 1
weirdness_constraint	number	否 / 依条件	创意约束，0–1，最多两位小数；生成时仅限自定义模式。 min: 0; max: 1
audio_weight	number	否 / 依条件	音频影响程度，0–1，最多两位小数；生成时仅限自定义且非纯音乐模式。 min: 0; max: 1
variety	integer	否 / 依条件	多样性，0–4 整数，自定义生成默认 1。 min: 0; max: 4
upload_url	string	是	公开HTTPS音频URL，端口443且不含用户名密码。接受包含可读音轨的MP3/WAV/FLAC/OGG/M4A/AAC，大小限制见具体操作。
title	string	是	标题。生成/翻唱最多 80 字符，续写及其他操作最多 100 字符；自定义生成必填。 maxLength: 100
negative_tags	string	是	排除的风格；增加伴奏或人声时必填。 maxLength: 1000
style	string	是	音乐风格，最多 1000 字符；简单生成时计为一个附件。 maxLength: 1000
lyrics	string	否 / 依条件	歌词，最多5000字符；传入时优先于prompt。 maxLength: 5000
prompt	string	否 / 依条件	备用歌词，最多5000字符；仅省略lyrics时使用。 maxLength: 5000
model	string	否 / 依条件	Suno 版本：V6、V6_MINI 或 V6_WILD；续写需与生成原曲版本一致。 values: V6, V6_MINI, V6_WILD; default: V6

输入与限制

下方Schema列出支持字段、类型和基础限制；还须遵守“重要条件”，跨字段与来源资源校验不完全体现在JSON Schema中。未知参数会被拒绝。URL 参数仅接受公开 HTTPS 地址，不接受文件对象。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "vocal_gender": {
      "type": "string",
      "enum": [
        "m",
        "f"
      ],
      "description": "m 或 f，表示人声倾向，不保证特定声音身份；生成时仅限自定义模式。"
    },
    "style_weight": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "风格影响程度，0–1，最多两位小数；生成时仅限自定义模式。"
    },
    "weirdness_constraint": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "创意约束，0–1，最多两位小数；生成时仅限自定义模式。"
    },
    "audio_weight": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "音频影响程度，0–1，最多两位小数；生成时仅限自定义且非纯音乐模式。"
    },
    "variety": {
      "type": "integer",
      "minimum": 0,
      "maximum": 4,
      "description": "多样性，0–4 整数，自定义生成默认 1。"
    },
    "upload_url": {
      "type": "string",
      "format": "uri",
      "description": "公开HTTPS音频URL，端口443且不含用户名密码。接受包含可读音轨的MP3/WAV/FLAC/OGG/M4A/AAC，大小限制见具体操作。"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "标题。生成/翻唱最多 80 字符，续写及其他操作最多 100 字符；自定义生成必填。"
    },
    "negative_tags": {
      "type": "string",
      "maxLength": 1000,
      "description": "排除的风格；增加伴奏或人声时必填。"
    },
    "style": {
      "type": "string",
      "maxLength": 1000,
      "description": "音乐风格，最多 1000 字符；简单生成时计为一个附件。"
    },
    "lyrics": {
      "type": "string",
      "maxLength": 5000,
      "description": "歌词，最多5000字符；传入时优先于prompt。"
    },
    "prompt": {
      "type": "string",
      "maxLength": 5000,
      "description": "备用歌词，最多5000字符；仅省略lyrics时使用。"
    },
    "model": {
      "default": "V6",
      "type": "string",
      "enum": [
        "V6",
        "V6_MINI",
        "V6_WILD"
      ],
      "description": "Suno 版本：V6、V6_MINI 或 V6_WILD；续写需与生成原曲版本一致。"
    }
  },
  "required": [
    "upload_url",
    "title",
    "negative_tags",
    "style"
  ],
  "additionalProperties": false
}

重要条件

音频URL必须包含可读且时长大于零的MP3/WAV/FLAC/OGG/M4A/AAC音轨，每个文件最多500 MiB。URL须为可公开读取的HTTPS地址、端口443，不含用户名密码或私网地址，且应持续可访问直到任务结束。
歌曲音频可能为MP3或M4A；需要真正MP3时使用suno_export_mp3。可选封面无法获取时可能为null，不影响音频使用。
上传文件保留24小时，生成文件保留14天，任务详情保留30天；复用文件沿用原到期时间。有效Voice/Persona身份映射与任务日志清理分开处理，请及时下载需长期保存的文件。

结果 Schema

创建响应为 {code:200,msg:“success”,data:{task_id}}，轮询 GET /api/v1/tasks/{task_id}。成功时 data.result 为符合下方 Schema 的对象，其他状态为 null；input 仍为 JSON 字符串。

{
  "type": "object",
  "required": [
    "code",
    "msg",
    "data"
  ],
  "properties": {
    "code": {
      "const": 200
    },
    "msg": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "required": [
        "callbackType",
        "task_id",
        "data"
      ],
      "properties": {
        "callbackType": {
          "const": "complete"
        },
        "task_id": {
          "type": "string"
        },
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "id",
              "audio_url",
              "stream_audio_url",
              "image_url",
              "prompt",
              "lyrics",
              "model_name",
              "title",
              "createTime",
              "duration",
              "tags",
              "source_audio_url",
              "source_image_url",
              "source_stream_audio_url"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "audio_url": {
                "type": "string"
              },
              "stream_audio_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "image_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "prompt": {
                "type": "string"
              },
              "lyrics": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "model_name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "title": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "createTime": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "duration": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "tags": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "source_audio_url": {
                "type": "string"
              },
              "source_image_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "source_stream_audio_url": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        }
      }
    }
  }
}

歌曲duration单位为秒，任务duration单位为毫秒；createTime是毫秒Unix时间戳或null。目前stream_audio_url和source_stream_audio_url均为null；source_audio_url/source_image_url与audio_url/image_url指向同一本站托管副本，并非供应商直链。请遍历实际歌曲数组，注册上传音频不代表新生成两首歌曲。

开始使用 APIstable（必读）

模型市场

调用步骤

创建任务

受理响应

参数速查

输入与限制

重要条件

结果 Schema

相关流程

授权

请求体

响应

​调用步骤

​创建任务

​受理响应

​参数速查

​输入与限制

​重要条件

​结果 Schema

​相关流程

授权

请求体

响应

调用步骤

创建任务

受理响应

参数速查

输入与限制

重要条件

结果 Schema

相关流程