# Suno URL File Upload

> Common

Upload a remote HTTP/HTTPS file to the specified Suno storage path.
The `data.downloadUrl` in the successful response can be used as a file URL parameter for other Suno
endpoints, such as the audio separation endpoint.

## Endpoint

`POST https://api.modelverse.cn/v1/Suno/file-url-upload`

## Request Body

## Responses

- **200** — File upload succeeded.
- **400** — Invalid request parameters, such as missing required fields or an invalid URL.
- **401** — ModelVerse API Key is missing or invalid.
- **default** — Suno or gateway error.

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "Suno URL File Upload API",
    "version": "1.0.0",
    "description": "Suno file URL upload API. The endpoint accepts an HTTP/HTTPS file URL accessible by the server,\nuploads the remote file to Suno, and returns file metadata and a temporary download URL.\n\n**Usage:**\n- `fileUrl` must be an HTTP or HTTPS URL accessible by the server.\n- `uploadPath` is required and must not start or end with `/`.\n- `fileName` is an optional file name including its extension. If omitted, a random file name is generated. An existing file with the same name is overwritten; caching may delay the visible effect.\n- Uploaded files are temporary; download URLs expire, so save the file promptly after upload.\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API server"
    }
  ],
  "tags": [
    {
      "name": "Suno File Management",
      "description": "Suno remote file upload operations."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/Suno/file-url-upload": {
      "post": {
        "tags": [
          "Suno File Management"
        ],
        "operationId": "uploadSunoFileFromURL",
        "summary": "Suno URL File Upload",
        "description": "Upload a remote HTTP/HTTPS file to the specified Suno storage path.\nThe `data.downloadUrl` in the successful response can be used as a file URL parameter for other Suno\nendpoints, such as the audio separation endpoint.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SunoFileURLUploadRequest"
              },
              "examples": {
                "customFileName": {
                  "summary": "Upload with a specified file name",
                  "value": {
                    "fileUrl": "https://example.com/audio/source.mp3",
                    "uploadPath": "audio/imported",
                    "fileName": "source.mp3"
                  }
                },
                "autoFileName": {
                  "summary": "Generate or extract the file name automatically",
                  "value": {
                    "fileUrl": "https://example.com/audio/source.mp3",
                    "uploadPath": "audio/imported"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "File upload succeeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoFileURLUploadResponse"
                },
                "example": {
                  "success": true,
                  "code": 200,
                  "msg": "File upload succeeded",
                  "data": {
                    "fileName": "source.mp3",
                    "filePath": "audio/imported/source.mp3",
                    "downloadUrl": "https://tempfile.example.com/audio/imported/source.mp3",
                    "fileSize": 154832,
                    "mimeType": "audio/mpeg",
                    "uploadedAt": "2026-08-12T12:00:00.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters, such as missing required fields or an invalid URL.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoFileUploadErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "ModelVerse API Key is missing or invalid."
          },
          "default": {
            "description": "Suno or gateway error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoFileUploadErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "Use a ModelVerse API Key with `Authorization: Bearer <API_KEY>` in the `Authorization` header."
      }
    },
    "schemas": {
      "SunoFileURLUploadRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "fileUrl",
          "uploadPath"
        ],
        "properties": {
          "fileUrl": {
            "type": "string",
            "format": "uri",
            "pattern": "^https?://[^\\s]+$",
            "description": "A remote file URL accessible by the server; only HTTP and HTTPS are supported."
          },
          "uploadPath": {
            "type": "string",
            "minLength": 1,
            "pattern": "^(?!/)(?!.*\\/$).+",
            "description": "File upload directory; must not start or end with `/`."
          },
          "fileName": {
            "type": "string",
            "minLength": 1,
            "description": "Optional file name without a path; a name is generated or extracted when omitted."
          }
        }
      },
      "SunoFileURLUploadResponse": {
        "type": "object",
        "additionalProperties": false,
        "example": {
          "success": true,
          "code": 200,
          "msg": "File upload succeeded",
          "data": {
            "fileName": "source.mp3",
            "filePath": "audio/imported/source.mp3",
            "downloadUrl": "https://tempfile.example.com/audio/imported/source.mp3",
            "fileSize": 154832,
            "mimeType": "audio/mpeg",
            "uploadedAt": "2026-08-12T12:00:00.000Z"
          }
        },
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "code": {
            "type": "integer",
            "example": 200
          },
          "msg": {
            "type": "string",
            "example": "File upload succeeded"
          },
          "data": {
            "$ref": "#/components/schemas/SunoUploadedFile"
          }
        }
      },
      "SunoUploadedFile": {
        "type": "object",
        "additionalProperties": false,
        "example": {
          "fileName": "source.mp3",
          "filePath": "audio/imported/source.mp3",
          "downloadUrl": "https://tempfile.example.com/audio/imported/source.mp3",
          "fileSize": 154832,
          "mimeType": "audio/mpeg",
          "uploadedAt": "2026-08-12T12:00:00.000Z"
        },
        "properties": {
          "fileName": {
            "type": "string",
            "example": "source.mp3"
          },
          "filePath": {
            "type": "string",
            "example": "audio/imported/source.mp3"
          },
          "downloadUrl": {
            "type": "string",
            "format": "uri",
            "example": "https://tempfile.example.com/audio/imported/source.mp3"
          },
          "fileSize": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "example": 154832
          },
          "mimeType": {
            "type": "string",
            "example": "audio/mpeg"
          },
          "uploadedAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-08-12T12:00:00.000Z"
          }
        }
      },
      "SunoFileUploadErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean"
          },
          "code": {
            "type": "integer"
          },
          "msg": {
            "type": "string"
          }
        }
      }
    }
  }
}
```