---
title: "upload music"
method: POST
path: "/api/v1/sonic/upload"
tags: ["sonic"]
---

# upload music

`POST /api/v1/sonic/upload`

## Request

- Base URL: `https://api.musicapi.ai`
- URL: `https://api.musicapi.ai/api/v1/sonic/upload`
- Auth: HTTP bearer

Upload local songs and get the clip id for subsequent operations.

**Sync mode (default):** Returns `clip_id` directly in the response.

**Async mode:** When `callback_url` is provided, returns a `task_id` immediately and sends the result to your callback URL when the upload completes.

## Request body

- object
  - `url` string, required: The online music url you want to upload. It must be copyright-free music and be publicly accessible.
  - `callback_url` string: Optional. An HTTPS URL to receive the upload result asynchronously. When provided, the API returns a task_id immediately instead of waiting for the upload to complete. The callback will receive a POST request with the upload result (including clip_id) once processing is done.
  - `callback_secret` string: Optional. A secret string used to sign the callback payload for verification. Only used when callback_url is provided.

## Response `200`

Upload successful. Returns clip_id in sync mode, or task_id in async mode.

- union
  - object: Returned when callback_url is not provided
    - `code` integer, required
    - `clip_id` string, required: The sonic clip id after uploading
    - `message` string, required
  - object: Returned when callback_url is provided
    - `code` integer, required
    - `task_id` string, required: The task id for tracking the upload progress
    - `message` string, required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Insufficient credits
- `500`: Upload failed

---

[API](https://skmtc.dev/musicapi/apis/musicapi-docs-suno-style-ai-music-generation-api.md) - [All operations](https://skmtc.dev/musicapi/apis/musicapi-docs-suno-style-ai-music-generation-api/llms.txt) - [OpenAPI document](https://skmtc.dev/musicapi/apis/musicapi-docs-suno-style-ai-music-generation-api/revisions/f94a2c7ed4a1?raw)