上传源音频 API

更新于 2026-09-15 · Suno-API 团队

接口说明

上传源音频用于把本地音频或远程音频上传为后续翻唱、续写、替换、分轨等能力可使用的源 clip。

接口地址: POST /api/music/upload-source

计费: 免费。该接口只上传源音频，不开始生成任务。

推荐用法：它是「两步式翻唱」的第 1 步。 先用本接口把音频传上来（免费、失败可随时重试），拿到返回的 clip_id；确认上传成功（status 为完成态）后， 再调用基于源 clip 翻唱 API 发起翻唱——那一步的请求体只有几百字节， 不会因为音频太大而在传输中被截断。相比一次性接口上传后翻唱 API， 这种拆法在音频较大、网络不稳定、或同一份素材要复用多次（续写 / 替换 / 分轨）时更稳。

选择上传方式

上传完成后，务必先确认响应里的 status 已是完成态、并保存 clip_id，再进入第 2 步； 上传失败不会扣费、也不会产生生成任务，直接重试即可。

file_url 是由平台服务器主动下载，不是浏览器跳转。 你的浏览器能打开该地址，不代表平台生产服务器也能下载。临时签名过期、文件被清理、URL 参数被截断、防盗链、仅内网可访问，都会导致服务器下载失败。

请求参数

Headers

JSON 请求：

multipart 请求不要手动指定 Content-Type，由客户端自动生成。

Body 参数

file、file_url、file_base64 至少提供一种。推荐优先使用 multipart file。

使用 file_url 前必须预检

平台会在服务端对 file_url 发起 HTTP GET，并在取得完整音频后再上传。调用上传接口前，请从一台普通公网服务器执行：

curl -L --max-time 30 -D - -o /dev/null "https://example.com/source.mp3"

Windows 可将输出路径写成 NUL：

curl.exe -L --max-time 30 -D - -o NUL "https://example.com/source.mp3"

只有同时满足以下条件，file_url 才应交给上传接口：

• 最终状态码为 HTTP 200；
• 没有跳转到登录页、验证码页或网页；
• Content-Type 是 audio/* 或该文件实际类型对应的音频 MIME；
• Content-Length 大于 0；
• 下载内容不是 HTML、JSON 错误页或空文件；
• 不依赖 Cookie、浏览器登录态、Referer、特定 IP 白名单；
• 调用上传接口时，签名和文件本身仍未过期或删除。

如果返回 401、403、404、410，或者最终只得到 HTML 页面，平台服务器同样无法使用这个地址。

p3-bot-workflow-sign.byteimg.com 等 ByteDance 临时文件地址通常带有效期，并可能绑定原工作流环境。常见失败原因包括：

1. 签名已经过期；
2. 临时文件已被清理或移动；
3. URL 查询参数缺失、被截断或被日志系统改写；
4. 地址只允许原业务环境访问；
5. 来源域名、IP 或防盗链限制阻止平台服务器下载。

这类地址应在生成后立即使用；如果需要稳定重试，请改用 multipart 上传文件本人，或先把文件转存到长期有效、公网可访问的对象存储。

file_url download failed: HTTP 404 表示 URL 已失效、文件被删除或路径参数不完整； HTTP 401/403 通常表示鉴权、防盗链或 IP 限制； one of file_path, file_base64, file_url, or multipart file is required 表示请求没有携带任何音频内容。 如果服务端返回 HTML 或登录页，也应检查 URL 的最终跳转与内容类型。外层 [... ] 请求 HTTP 失败, code:500 可能只是平台对内部上传错误的通用包装，服务端根因中会明确包含 file_url download failed 时，应按上面的地址可用性规则排查。

upload-source 是免费上传接口。file_url 下载失败时不会生成 clip_id、不会创建歌曲任务、不会调用生成模型，也不会扣费，因此不需要退款。

JSON 请求示例

curl -X POST https://www.suno-api.io/api/music/upload-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "file_url": "https://example.com/source.mp3",
    "file_name": "source.mp3",
    "upload_type": "file_upload"
  }'

multipart 请求示例

curl -X POST https://www.suno-api.io/api/music/upload-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.mp3" \
  -F "file_name=source.mp3" \
  -F "upload_type=file_upload" \
  -F "model=suno-v6"

Python multipart 示例：

import requests

with open("source.mp3", "rb") as audio:
    response = requests.post(
        "https://www.suno-api.io/api/music/upload-source",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        data={
            "file_name": "source.mp3",
            "upload_type": "file_upload",
            "model": "suno-v6",
        },
        files={"file": ("source.mp3", audio, "audio/mpeg")},
        timeout=300,
    )

response.raise_for_status()
print(response.json())

multipart 时不要手动设置 Content-Type，让客户端自动生成 boundary。

响应结果

{
  "clip_id": "uploaded_clip_id",
  "status": "complete",
  "title": "source.mp3",
  "image_url": "https://...",
  "audio_url": "https://...",
  "display_tags": "pop, vocal",
  "inferred_description": "uploaded source audio",
  "clip_metadata": {}
}

请保存响应中的 clip_id，后续翻唱、续写、替换或分轨使用该 ID，不要再次依赖原始临时 URL。

上传前排查清单

• 本地文件优先使用 multipart，文件字段名为 file；
• multipart 请求没有手动设置 Content-Type；
• 使用 file_url 时，地址是完整、未截断的 HTTPS URL；
• file_url 从普通公网服务器发起 GET 返回 HTTP 200；
• 最终内容类型是音频，不是登录页或 HTML；
• 临时签名、文件和查询参数在调用上传接口时仍然有效；
• 地址不依赖 Cookie、浏览器登录态、Referer 或来源 IP；
• 上传成功并拿到 clip_id 后，再发起后续生成任务。