上传音频

把外部音频接入 Suno 流程，异步任务
只接受公网可读的 HTTP(S) 直链，不收二进制文件
上传完成后的 task_id 可作为翻唱、续写的源

POST/v1/music/generations/uploadTask

认证

string必填

所有接口均使用 Bearer Token 进行认证。

获取 API Key：访问控制台创建。

请求时在请求头中添加：

Authorization: Bearer YOUR_OAIRoute_KEY

请求参数

请求体是 JSON，不是 multipart/form-data。

string必填

已上传至对象存储、可公开读取的音频直链。

本机路径与 blob: URL 都不行，必须是外部能访问到的 HTTP(S) 地址。

本接口不接收二进制文件。想直接传文件是做不到的，必须先把文件放到能公网访问的地方（对象存储、图床、CDN），再把直链传进来。

不接受的参数

version、audio_format，以及文档未列出的其他参数都会被忽略。

响应

integer

响应状态码。

data[] 的元素字段 · 2 项

string

任务状态，取值为 submitted。

string

任务唯一标识，用于轮询及后续操作引用。

上传之后怎么用

轮询拿到完成的 task_id，把它作为后续操作的源：

{
  "model": "suno",
  "task_id": "上传任务的 task_id",
  "audio_index": 1,
  "tags": "jazz, piano trio"
}

配合 audio_index=1 即可引用上传的音频做翻唱、续写、分轨等操作。

上传结果可能只返回 audio_id，不保证返回可播放的 audio_url。如果后续要用音频本身，轮询时检查 result.music[] 里是否有地址，没有的话按 audio_id 处理。

Poll until the task is complete, then use its task_id as the source for later operations:

{
  "model": "suno",
  "task_id": "the upload task's task_id",
  "audio_index": 1,
  "tags": "jazz, piano trio"
}

Together with audio_index=1 you can reference the uploaded audio for covers, extensions, stem extraction, and more.

The upload result may return only audio_id and isn't guaranteed to return a playable audio_url. If you need the audio itself later, check during polling whether result.music[] has an address; if not, work with audio_id.

怎么拿到公网直链

存储方式	做法
对象存储（S3、OSS、COS）	上传后把对象设为公共读，复制对象 URL
图床或音床	上传后取直链
自建服务器	放到可公开访问的静态目录

要点是不需要登录、不需要签名就能下载。带鉴权的私有链接会被拒。

Storage	Approach
Object storage (S3, OSS, COS)	Upload, set the object to public-read, copy the object URL
Image or audio host	Upload, then copy the direct link
Your own server	Place it in a publicly accessible static directory

The point is that it can be downloaded without login and without signing. Private links behind authentication are rejected.

错误码

错误响应的格式、状态码与重试建议见错误码与限流，常见报错的排查步骤见常见问题。

使用示例

导入外部音频

audioFilePath 填公网可直接下载的地址。本地文件路径和 blob: 都会被拒绝，报 invalid_request_error。

拿到 task_id 后继续操作

上传本身也是一个异步任务。返回的 task_id 可以当作源音轨，传给裁剪、续写、翻唱等接口。

TASK=$(curl -s --request POST https://api.oairoute.com/v1/music/generations/uploadTask \
  -H "Authorization: Bearer $YOUR_OAIRoute_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audioFilePath":"https://example.com/song.mp3"}' \
  | jq -r '.data[0].task_id')

curl --request POST https://api.oairoute.com/v1/music/generations/crop \
  -H "Authorization: Bearer $YOUR_OAIRoute_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"task_id\":\"$TASK\",\"start_s\":12.5,\"end_s\":42}"

上传后先确认可用

部分来源只返回 audio_id，没有可播放的 audio_url。后面要拿音频本体时，先查一次任务，确认 result.music[] 里有地址。

curl --request GET \
  --url "https://api.oairoute.com/v1/music/tasks/$TASK" \
  --header "Authorization: Bearer $YOUR_OAIRoute_KEY" \
  | jq '.data.result.music[] | {id, audio_url}'

Importing external audio

audioFilePath takes a publicly downloadable address. Local file paths and blob: are both rejected with invalid_request_error.

Continuing work with the task_id

The upload itself is also an asynchronous task. The returned task_id can be used as the source track and passed to the crop, extend, cover, and other endpoints.

TASK=$(curl -s --request POST https://api.oairoute.com/v1/music/generations/uploadTask \
  -H "Authorization: Bearer $YOUR_OAIRoute_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audioFilePath":"https://example.com/song.mp3"}' \
  | jq -r '.data[0].task_id')

curl --request POST https://api.oairoute.com/v1/music/generations/crop \
  -H "Authorization: Bearer $YOUR_OAIRoute_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"task_id\":\"$TASK\",\"start_s\":12.5,\"end_s\":42}"

Confirming it's usable after upload

Some sources return only audio_id, with no playable audio_url. When you need the audio itself later, query the task once first to confirm result.music[] has an address.

curl --request GET \
  --url "https://api.oairoute.com/v1/music/tasks/$TASK" \
  --header "Authorization: Bearer $YOUR_OAIRoute_KEY" \
  | jq '.data.result.music[] | {id, audio_url}'