MusicAPI
HomeDocs
HomeDocs
  1. sonic
  • Introduction
  • Credits Usage Guide
  • Music API FAQ & Troubleshooting
  • Special Scenarios
  • Error handling
  • Webhook Integration Guide
  • sonic
    • Sonic Instructions
    • create / extend / cover / remaster / add vocals / add instrumental
      POST
    • upload and extend music
      POST
    • upload and cover music
      POST
    • create persona
      POST
    • sample
      POST
    • mashup
      POST
    • get BPM
      POST
    • get VOX
      POST
    • get wav
      POST
    • get midi
      POST
    • get lyrics timeline
      POST
    • upsample tags
      POST
    • stems basic
      POST
    • stems full
      POST
    • replace section
      POST
    • upload music
      POST
    • get music
      GET
  • riffusion(Deprecated)
    • Riffusion instructions
    • create music (with lyrics)
      POST
    • create music (with description)
      POST
    • cover music
      POST
    • extend music
      POST
    • replace music section
      POST
    • swap music sound
      POST
    • swap music vocals
      POST
    • upload
      POST
    • get music
      GET
  • producer
    • Producer instructions
    • Complete Request Examples
    • create music
    • upload
    • download
    • get music
  • studio(Unavailable)
    • Studio Instructions
    • description mode (Use case1)
    • extend mode (Use case2)
    • custom mode (Use case3)
    • instrumental mode (Use case4)
    • get music
  • lyrics generation
    • Make Lyrics
  • nuro
    • Nuro Instruction
    • Error handling
    • create vocal music
    • create instrument music
    • get music
  • get-credits
    GET
  • Schemas
    • 记录不存在
    • 参数不正确
HomeDocs
HomeDocs
  1. sonic

sample

POST
https://api.musicapi.ai/api/v1/sonic/sample
Generate a complete song from a short audio sample or hummed melody. This endpoint uses a clip segment as inspiration to create a full-length track.
Credits cost: 15

Note#

After testing, it is recommended to use the v5 model to obtain the best results.

Two Ways to Provide Audio Source#

Option 1: Using an existing clip ID (sample_clip_id)
Use sample_clip_id for songs generated through our service
Or use clip IDs obtained from the upload endpoint
Option 2: Using a URL (url) - Auto Upload
Provide a direct URL to your audio file
The API will automatically upload the audio and obtain a clip ID
This is a convenience feature that combines upload + sample in one call
Note: url and sample_clip_id are mutually exclusive - provide only one of them.

How to Use#

1.
Provide either sample_clip_id (existing clip) or url (audio file URL for auto-upload)
2.
Specify the sample segment using chop_sample_start_s and chop_sample_end_s
3.
Choose between custom lyrics mode (custom_mode: true) or AI description mode (custom_mode: false)
4.
Select a music model version
5.
Optionally customize style, vocals, and other parameters

Custom Mode vs AI Description Mode#

Custom Mode (custom_mode: true):
You provide the exact lyrics via the prompt parameter
Full control over the lyrical content
Requires prompt field
AI Description Mode (custom_mode: false):
AI generates lyrics based on your description
Provide a description via gpt_description_prompt
AI creates appropriate lyrics matching your description
Requires gpt_description_prompt field

Polling Result#

Use the task query endpoint with the returned task_id to poll for results. Recommended polling interval: 15-25 seconds.

Request

Authorization
JWT Bearer
Add the parameter
Authorization
to Headers
Example:
Authorization: ********************
or
Body Params application/json

Examples
{
    "sample_clip_id": "abc123-def456-sample",
    "chop_sample_start_s": 0,
    "chop_sample_end_s": 30,
    "custom_mode": true,
    "mv": "chirp-v4-5-plus",
    "make_instrumental": false,
    "prompt": "[Verse 1]\nInspired by this melody\nCreating something beautiful\n\n[Chorus]\nFrom a simple hum\nA full song has come",
    "title": "Melody Dreams",
    "tags": "pop, melodic, uplifting",
    "style_weight": 0.7
}

Request Code Samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location --request POST 'https://api.musicapi.ai/api/v1/sonic/sample' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "sample_clip_id": "abc123-def456-sample",
    "chop_sample_start_s": 0,
    "chop_sample_end_s": 30,
    "custom_mode": true,
    "mv": "chirp-v4-5-plus",
    "make_instrumental": false,
    "prompt": "[Verse 1]\nInspired by this melody\nCreating something beautiful\n\n[Chorus]\nFrom a simple hum\nA full song has come",
    "title": "Melody Dreams",
    "tags": "pop, melodic, uplifting",
    "style_weight": 0.7
}'

Responses

🟢200success
application/json
success
Body

Examples
{
    "code": 200,
    "message": "success",
    "task_id": "81ed9f60-56ae-48c1-9c46-33a8220dfca7"
}
Modified at 2026-01-31 15:04:50
Previous
create persona
Next
mashup
Built with