← Back to API Documentation

Upload & Remaster Audio Endpoint

Overview

The upload endpoint allows you to upload an audio file from a URL and remaster it using Suno AI's upsampling technology. The endpoint handles the entire workflow: file upload, processing, and remastering.

🔗 Quick Links

Endpoint

POST /[accountId]/api/upload

Request

Headers

Content-Type: multipart/form-data

Body (Form Data)

fileUrl (string, required)
Publicly accessible URL to the audio file to upload

Example Request

curl -X POST https://your-domain.com/[accountId]/api/upload \
  -F "fileUrl=https://example.com/audio.mp3"

const formData = new FormData();
formData.append('fileUrl', 'https://example.com/audio.mp3');

const response = await fetch('/[accountId]/api/upload', {
  method: 'POST',
  body: formData
});

Response

Success Response (200 OK)

When the upload and remastering completes successfully:

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Remastered Audio",
    "image_url": "https://cdn.suno.ai/image-12345.png",
    "lyric": "Original prompt or lyrics",
    "audio_url": "https://cdn.suno.ai/audio-12345.mp3",
    "video_url": "https://cdn.suno.ai/video-12345.mp4",
    "created_at": "2025-12-09T14:30:00.000Z",
    "model_name": "chirp-ahi",
    "status": "complete",
    "gpt_description_prompt": "Description prompt",
    "prompt": "Original prompt",
    "type": "remaster",
    "tags": "rock, energetic",
    "negative_tags": "slow, sad",
    "duration": "180"
  }
]

Status Code: 200
Content-Type: application/json

Content Policy Violation (403 Forbidden)

When the uploaded file violates content policies (copyright, inappropriate content, or other policy violations):

{
  "error": "Uploaded audio matches existing work of art."
}

Status Code: 403
Content-Type: application/json

Important: The error message in the response body indicates the specific violation type. Common error messages include:

  • "Uploaded audio matches existing work of art." - Copyright violation
  • Other error messages from Suno API indicating various content policy violations

Note: Always check the error message content to determine the specific violation type. The 403 status code indicates a content policy violation, but the exact reason is provided in the error message.

Bad Request (400)

When required parameters are missing:

{
  "error": "No file URL provided"
}

Status Code: 400
Content-Type: application/json

Internal Server Error (500)

When an error occurs during processing:

{
  "error": "Internal server error: Failed to fetch file from URL: Not Found"
}

Status Code: 500
Content-Type: application/json

Possible Error Scenarios:

  • File URL is inaccessible or invalid
  • Network errors during file fetch
  • S3 upload failures
  • Suno API errors
  • Authentication failures
  • Timeout errors

Method Not Allowed (405)

When using an unsupported HTTP method:

Status Code: 405
Headers: Allow: POST

Processing Workflow

The endpoint performs the following steps:

  1. Request Upload Slot - Gets a pre-signed S3 upload URL from Suno
  2. Upload to S3 - Uploads the file to Suno's S3 bucket
  3. Finalize Upload - Notifies Suno that upload is complete
  4. Poll Upload Status - Waits for Suno to process the upload
  5. Initialize Clip - Creates a clip from the uploaded audio
  6. Upsample/Remaster - Applies AI remastering using chirp-ahi model
  7. Return Results - Returns the remastered audio information

Error Handling

Content Policy Violations (403)

The endpoint returns 403 Forbidden when the uploaded content violates Suno's content policies. This can include:

  • Copyright violations (e.g., "Uploaded audio matches existing work of art.")
  • Inappropriate content
  • Other content policy violations

Important:

  • This is a content policy violation, not a technical error. The request was processed successfully, but the content was rejected.
  • Always check the error message in the response body to determine the specific violation type. The error message will indicate whether it's a copyright issue, inappropriate content, or another policy violation.
  • Do not assume all 403 errors are copyright-related - check the error message content.

Retry Logic

  • The endpoint does not automatically retry failed requests
  • Clients should implement their own retry logic for transient errors (500)
  • Do not retry 403 errors (content policy violations)

Rate Limiting

  • Rate limits are managed per account
  • Each account has its own queue for serialized request processing
  • Concurrent requests for the same account are queued automatically

File Requirements

Supported Formats

  • Audio files (MP3, WAV, etc.)
  • File must be publicly accessible via HTTP/HTTPS
  • File size limits apply (check Suno API documentation)

File URL Requirements

  • Must be publicly accessible (no authentication required)
  • Must return the file directly (not a redirect to a download page)
  • Must be a valid audio file format

Example Usage

JavaScript/TypeScript

async function uploadAndRemaster(fileUrl: string, accountId: string) {
  const formData = new FormData();
  formData.append('fileUrl', fileUrl);

  const response = await fetch(`/${accountId}/api/upload`, {
    method: 'POST',
    body: formData
  });

  if (response.status === 200) {
    const audioInfo = await response.json();
    console.log('Remastered audio:', audioInfo[0].audio_url);
    return audioInfo;
  } else if (response.status === 403) {
    const error = await response.json();
    console.error('Content policy violation:', error.error);
    // Check error message to determine violation type
    if (error.error.includes('matches existing work')) {
      throw new Error('Copyright violation: ' + error.error);
    } else {
      throw new Error('Content policy violation: ' + error.error);
    }
  } else {
    const error = await response.json();
    throw new Error('Upload failed: ' + error.error);
  }
}

Python

import requests

def upload_and_remaster(file_url: str, account_id: str):
    url = f"https://your-domain.com/{account_id}/api/upload"
    files = {"fileUrl": (None, file_url)}
    
    response = requests.post(url, files=files)
    
    if response.status_code == 200:
        return response.json()
    elif response.status_code == 403:
        error = response.json()
        error_msg = error.get('error', 'Unknown violation')
        # Check error message to determine violation type
        if 'matches existing work' in error_msg:
            raise Exception(f"Copyright violation: {error_msg}")
        else:
            raise Exception(f"Content policy violation: {error_msg}")
    else:
        error = response.json()
        raise Exception(f"Upload failed: {error['error']}")

Status Code Summary

| Status | Meaning | When It Occurs | |-------|---------|----------------| | 200 | Success | Upload and remastering completed successfully | | 400 | Bad Request | Missing fileUrl parameter | | 403 | Forbidden | Content policy violation (check error message for specific violation type) | | 405 | Method Not Allowed | Using non-POST HTTP method | | 500 | Internal Server Error | Server error during processing |

Notes

  1. Processing Time: The remastering process can take 30-60 seconds or more depending on file size and server load
  2. CORS: All responses include CORS headers for cross-origin requests
  3. Account Routing: Always use /[accountId]/api/upload format with a specific account ID
  4. Error Messages: 500 errors include the processing step where failure occurred for debugging

Best Practices

  1. Handle 403 Errors Gracefully: Always check the error message content to determine the specific violation type (copyright, inappropriate content, etc.) and inform users accordingly
  2. Implement Timeouts: Set appropriate timeouts (60+ seconds) for the request
  3. Validate File URLs: Ensure the file URL is accessible before sending the request
  4. Error Retry: Only retry on 500 errors, not on 403 (content policy violations)
  5. Monitor Processing: The endpoint logs each processing step for debugging
← Back to API Documentation