Recovery Audio Records
Retrieve and re-generate valid signed CDN media URLs for historic music generation jobs. If older audio download links or stream URLs have expired, submit the original task ID to refresh high-speed media access and re-index metadata.
Key Capabilities & CDN Renewal
- Signed URL Renewal: Re-signs and regenerates valid CDN download and streaming URLs for both audio tracks and cover artwork.
- Lossless Metadata Retrieval: Restores title, duration, waveform status, and variation metadata associated with the historic task.
- Two-Way Verification: Receive asynchronous results via your configured
callBackUrl, or poll the dedicated query endpoint anytime. - Economical Cost: Only 5 credits per recovery task. If the original task record cannot be found, credits are instantly refunded.
Dedicated Recovery Query Endpoint
GET PollingIn addition to Webhook callbacks, you can actively poll the recovery status via query parameter:
Task still executing. Continue polling every 3–5 seconds.
Recovery completed! Returns renewed audio URLs and metadata.
Recovery failed or historic tracks expired permanently.
Validation Rules & Constraints
Original Task ID
The task_id must be a valid task ID previously created by a music generation job.
Asynchronous Webhook
Cloud storage retrieval runs asynchronously. Configure callBackUrl to receive the restored file list as soon as re-signing completes.
Authentication & Headers
| Header | Requirement | Description |
|---|---|---|
| Authorization | required | Bearer YOUR_API_KEY Secret API key generated in your dashboard. |
| Content-Type | required | application/json Request body format. |
Request Body Parameters
3 fieldstask_idstringrequiredUnique identifier of the historic music generation task whose audio and media URLs need to be restored.
taskTypestringoptionalExplicit task routing identifier. Can be set to "recovery_audio".
callBackUrlstringoptionalPublic HTTPS webhook URL to receive asynchronous completion notification when media recovery finishes.
When Callbacks Are Sent
The SongMesh API automatically triggers an HTTP POST request to your designated callBackUrl under these events:
- Recovery task queued and cloud archive lookup started
- Audio tracks, stream endpoints, and artwork re-indexed
- Fresh signed CDN URLs generated and delivered to webhook (code: 200)
- Task failed if the task_id does not exist or historical records expired permanently (code: 400 or 500)
Webhook Payload Format
{
"code": 200,
"msg": "All generated successfully.",
"data": {
"task_id": "5c7901ab2c3d4e5f6a7b8c9d0e1f2a3b",
"data": [
{
"id": "8ca376e7-5b62-49d9-bbd3-08aaf2c6dd27",
"audio_url": "https://file.aiquickdraw.com/s/04e6789a-bcde-f012-3456-789abcdef012.mp3",
"stream_audio_url": "https://file.aiquickdraw.com/s/stream_04e6789a.mp3",
"image_url": "https://file.aiquickdraw.com/s/cover_04e6789a.png",
"title": "Midnight Echoes",
"duration": 218.4,
"status": "complete"
},
{
"id": "9db487f8-6c73-40ea-cce4-19bbf3d7ee38",
"audio_url": "https://file.aiquickdraw.com/s/15f789ab-cdef-0123-4567-89abcdef0123.mp3",
"stream_audio_url": "https://file.aiquickdraw.com/s/stream_15f789ab.mp3",
"image_url": "https://file.aiquickdraw.com/s/cover_15f789ab.png",
"title": "Midnight Echoes (Variant 2)",
"duration": 224.1,
"status": "complete"
}
]
}
}Callback Payload Fields
| Field | Type | Description |
|---|---|---|
code | integer | HTTP status code (200: Success, 400: Invalid task ID, 500: Server error). |
msg | string | Execution status message ("All generated successfully." or error details). |
data.task_id | string | Original music generation task identifier that was recovered. |
data.data | array | Array of restored audio track objects containing audio_url, stream_audio_url, image_url, and duration. |
Receiver Implementation Example
// Next.js App Router Webhook Receiver (/api/webhook/suno/route.ts)
import { NextRequest, NextResponse } from 'next/server';
export async function POST(req: NextRequest) {
const payload = await req.json();
const { code, msg, data } = payload;
if (code === 200 && Array.isArray(data?.data)) {
console.log(`Recovery task ${data.task_id} completed successfully!`);
data.data.forEach((track: any) => {
console.log(`Restored Track "${track.title}" (ID: ${track.id})`);
console.log(`Fresh Audio URL: ${track.audio_url}`);
console.log(`Streaming URL: ${track.stream_audio_url}`);
});
// Update your database with the renewed signed CDN URLs
} else {
console.error(`Audio recovery failed (${code}): ${msg}`);
}
return NextResponse.json({ received: true });
}Webhook Security Recommendation
Always verify incoming webhook payloads on your server. Respond with a 200 OK immediately after parsing the payload to prevent redundant delivery retries from the webhook dispatcher.
curl -X POST "https://api.sunoapi.top/api/v1/createTask" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"taskType": "recovery_audio",
"task_id": "5c7901ab2c3d4e5f6a7b8c9d0e1f2a3b",
"callBackUrl": "https://api.yourdomain.com/webhook/suno"
}'{
"code": 200,
"msg": "success",
"data": {
"taskId": "dc1928bfcbc77cb6c85f3359a9c718b3"
}
}• CDN Lifetime: CDN URLs typically expire after 14 days. Use this endpoint whenever your users attempt to play or download older songs.
• Query Status: You can query the result anytime via GET /api/v1/suno/recovery/record-info?task_id=... without additional credit charges.
• Pricing: Only 5 credits per recovery task.
Need to restore expired audio tracks?
Generate your API key and re-index historic music generation URLs with high-speed CDN delivery.