> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Suno MP3 URL API 對接說明

> Suno Music Generation 整合指南 - Ace Data Cloud

Suno MP3 URL API 為已有音樂生成一個路徑以 `.mp3` 結尾的可播放地址，適用於舊下載鏈接失效、移動端播放或需要重新獲取公開音頻 URL 的場景。

必填參數 `audio_id` 是 Suno 音頻生成接口返回的音頻 ID。每次調用都會創建獨立的 MP3 URL 任務，不會修改原始音樂生成任務，也不會改變原音頻 ID。

## 同步調用

```python theme={null}
import requests

response = requests.post(
    "https://api.acedata.cloud/suno/mp3",
    headers={
        "accept": "application/json",
        "authorization": "Bearer <YOUR_API_TOKEN>",
        "content-type": "application/json"
    },
    json={"audio_id": "ef1ec21e-1540-4eb6-8fa5-26cb8b90d28f"},
    timeout=240
)
response.raise_for_status()
result = response.json()
print(result["data"][0]["file_url"])
```

成功時，`data[0].file_url` 是可播放音頻地址。接口會優先轉存到 `https://cdn.acedata.cloud/suno/{audio_id}.mp3`；如果持久化失敗，則返回當前可用的原始媒體地址。

## 異步調用

處理時間較長時，可傳入 `async: true`：

```python theme={null}
submission = requests.post(
    "https://api.acedata.cloud/suno/mp3",
    headers={"authorization": "Bearer <YOUR_API_TOKEN>"},
    json={
        "audio_id": "ef1ec21e-1540-4eb6-8fa5-26cb8b90d28f",
        "async": True
    }
).json()

export_task_id = submission["task_id"]
```

隨後通過 `/suno/tasks` 查詢 `export_task_id`。也可以提供 `callback_url`，在任務完成後接收最終結果。同步響應、任務查詢和回調使用相同的終態數據結構。

## 注意事項

* `audio_id` 必須來自可識別的 Suno 音頻。
* MP3 URL 任務與原音樂生成任務相互獨立。
* 持久化失敗不會阻塞結果，會回退到原始媒體地址；請及時下載。
* 建議業務側在拿到結果後及時下載並按自己的數據保留策略保存。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.