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

# sample

`POST /api/v1/sonic/sample`

## Request

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

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: 20** on every model.

## Request body

- object
  - `url` string: URL of the audio file to use as sample. The API will automatically upload and obtain a clip ID. Mutually exclusive with sample_clip_id.
  - `sample_clip_id` string: The clip ID of the sample audio (from a previous upload or platform song). Mutually exclusive with url.
  - `chop_sample_start_s` number, required: Start time of the sample segment in seconds. Must be >= 0.
  - `chop_sample_end_s` number, required: End time of the sample segment in seconds. Must be greater than chop_sample_start_s.
  - `custom_mode` boolean, required: Set to true for custom lyrics mode (requires prompt), or false for AI description mode (requires gpt_description_prompt)
  - `mv` 'sonic-v6' | 'sonic-v6-wild' | 'sonic-v6-mini', required: Music model version. Supports both sonic-* and chirp-* formats. Suno retired v3.5 through v5.5 on 2026-09-09 and maps every retired id onto v6, so `sonic-v3-5`, `sonic-v4`, `sonic-v4-5`, `sonic-v4-5-plus`, `sonic-v5` and `sonic-v5-5` are still accepted and run v6 — existing integrations need no change.
  - `make_instrumental` boolean, required: Set to true to generate instrumental music without vocals, or false to include vocals.
  - `prompt` string: Custom lyrics for the song. Required when custom_mode is true. Maximum 3000 characters.
  - `gpt_description_prompt` string: Description for AI to generate lyrics. Required when custom_mode is false. Maximum 200 characters.
  - `title` string: Song title. Maximum 80 characters.
  - `tags` string: Style tags (comma-separated). Examples: pop, rock, jazz, electronic. Maximum 200 characters.
  - `negative_tags` string: Tags to avoid in the generated music (comma-separated). Use this to exclude unwanted styles or elements.
  - `style_weight` number: Controls how strongly the style tags influence the output. Value between 0 and 1. Higher values = stronger style adherence.
  - `weirdness_constraint` number: Controls creativity/randomness level. Value between 0 and 1. Higher values = more experimental/unusual output.
  - `audio_weight` number: Audio weight parameter. Value between 0 and 1.
  - `vocal_gender` 'f' | 'm': Vocal gender: 'f' for female, 'm' for male. Supported on every current model.
  - `auto_lyrics` boolean: Automatically generate lyrics. When true, the prompt field is used as a song description to generate both lyrics and style.
  - `webhook_url` string: HTTPS URL to receive webhook notifications when the task completes. Must be a valid HTTPS URL.
  - `webhook_secret` string: Secret key for webhook signature verification. Used to verify the webhook payload authenticity.

## Response `200`

success

- object
  - `code` number, required
  - `message` string, required
  - `task_id` string, required
  - `steps` object: Step-by-step results (only present when using url parameter)
    - `upload` object
      - `success` boolean
      - `clip_id` string
    - `sample` object
      - `success` boolean
      - `task_id` string

---

[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)