Model CenterGlobalAiOpc

SunoMusic Generation

POST/kyyReactApiServer/v2/model-center/tasks

Pricing

Turn an idea or your own lyrics into music with Suno. Use inspiration mode to describe what you want, or custom mode to provide lyrics, a style and a title. You can also create instrumental music without vocals.

Each request generates 2 song(s), each with its own task ID. Query each task to retrieve the audio and any accompanying artwork.

Quick start

Replace <API_KEY> in the example with your API key, edit the content and send the request.
Save every ID in task_ids and query each one every 3–5 seconds.
When status is completed, use the returned file URL to access your result.

Endpoint

http

POST https://zcbservice.aizfw.cn/kyyReactApiServer/v2/model-center/tasks

Authentication

Get Key

An API key is required. Use these headers when submitting a request, replacing <API_KEY> with your key.

http

Authorization: Bearer <API_KEY>
Content-Type: application/json

Choose how to create

Inspiration mode

No lyrics needed. Describe the theme, style, mood and singing language in gpt_description_prompt.

Custom lyrics

Turn your lyrics into a song. Provide prompt (lyrics), tags (style) and title (song name).

For instrumental music, describe it in gpt_description_prompt and set make_instrumental to true.

Every mode requires model and mv. Do not send gpt_description_prompt and prompt together. For your first request, copy the inspiration mode example below.

Request parameters

Send these parameters in the JSON request body. Always include required fields; provide the remaining fields for your chosen creation mode.

modelstringrequired

Model name

Use this model name.

Values and limits: suno_music

mvstringrequired

Music version

Music version; see the version guide below.

Values and limits: Allowed values: "chirp-hawk"; "chirp-hawk-wild"; "chirp-goose"

gpt_description_promptstring

Describe your idea

Required for description mode

Describe your idea, for example “An upbeat English pop song about a summer trip”. No lyrics needed. Do not also send prompt.

Values and limits: At least 1 characters

promptstring

Your lyrics

Required for custom lyrics

Lyrics for custom mode. Use [Verse] and [Chorus] for song sections and \n for line breaks. Do not also send gpt_description_prompt.

Values and limits: At least 1 characters; Up to 3000 characters

tagsstring

Music style

Required for custom lyrics

Style for custom mode, such as pop, acoustic, warm. Combine genres, instruments and mood.

Values and limits: At least 1 characters; Up to 200 characters

titlestring

Song title

Required for custom lyrics

Song title; required for custom mode.

Values and limits: At least 1 characters; Up to 80 characters

make_instrumentalboolean

Instrumental music

Whether to generate instrumental music: true for no vocals, false for a song.

negative_tagsstring

Styles to exclude

Styles or elements to exclude, such as heavy metal, drums. Omit if you have no exclusions.

Advanced options (optional)

You can omit metadata for your first request. Use these options to choose vocals or adjust creative controls.

Music versions

Use the model name shown on this page for model, and choose a music version below for mv. For V6, send "mv": "chirp-hawk".

mv value	Music version	Features and use cases
chirp-hawk	V6	Consistent and precise, suited to polished, high-quality songs.
chirp-hawk-wild	V6-wild	More creative and unpredictable, suited to exploring new ideas.
chirp-goose	V6-mini	Fast and efficient, suited to quick, lightweight creation.

Request examples

Choose a creation mode to view its request body. Full cURL, Python and JavaScript examples are available in the code panel. Install requests for Python; JavaScript examples can run with Node.js 18+.

JSON

{
  "model": "suno_music",
  "mv": "chirp-hawk",
  "gpt_description_prompt": "A warm English folk song about a summer reunion, with acoustic guitar and gentle female vocals."
}

Submission response

HTTP 202 means your request is queued. Generation takes time; query the tasks to retrieve your results.

Field	Description
task_ids	All task IDs for this request. Save and query each one to retrieve every result.
id	The first task ID.
status	queued means the task is waiting to start.
error	Error message, or null when no error occurred.

Query results

http

GET https://zcbservice.aizfw.cn/kyyReactApiServer/v2/model-center/tasks/{task_id}

task_idstringrequired

Replace {task_id} in the URL with one ID from the submission response task_ids, using the same API key. Query every task separately and retain all task IDs.

Task status

status	Meaning	What to do
queued	Queued	Query again in 3–5 seconds.
processing	Processing generation or file delivery	Query again in 3–5 seconds.
completed	Completed	Read the returned result fields and use the media URLs for playback or download.
failed	Generation failed	Read error for the cause and refund_status for refund progress.
delivery_exception	Generated, but the file is unavailable	Stop polling and contact support. Do not submit again.
manual_required	The task requires review	Stop polling, keep the task ID and contact support. Do not submit again.

Completed response example

JSON

{
  "id": "mcp_00000000000000000000000000000001",
  "model": "suno_music",
  "object": "audio",
  "created": 1792022400,
  "status": "completed",
  "amount": 0.25,
  "billing_status": "deducted",
  "refund_status": "none",
  "music_id": "Example text",
  "prompt": "Example text",
  "title": "Example text",
  "audio_url": "https://storage.example.com/audio.bin",
  "cover_image_url": "https://storage.example.com/cover_image.bin",
  "error": null
}

Example URLs and credits are illustrative. Actual charges follow your account pricing and task record. Generated files are available when status is completed.

Response fields

Field	Description
id	The task ID being queried.
model	The model used for generation.
object	Result type, such as audio or video.
created	Task creation time as a Unix timestamp in seconds.
status	Task status; completed means the result is ready.
amount / billing_status / refund_status	Credits consumed, charge status and refund status for this task.
error	Error message; null on success.
error_code	Platform error code, returned when an error occurs.

Media URL field	Description
audio_url	Audio download URL; returned on completion
cover_image_url	Image / cover URL; optional, omitted when unavailable

Result fields

Field	Type	Required	Description
music_id	string	No	歌曲id
prompt	string	No	歌词
title	string	No	歌曲名称

Media URLs refer to platform-stored files and can be used for playback or download. Optional URLs are omitted when unavailable.

Billing and troubleshooting

Each song is charged separately. A request with several songs costs the sum of their prices. If one song fails, only that song is refunded; successful songs remain usable. Check your account for current pricing.

Submission timeout: check whether the original request succeeded before submitting again to avoid duplicate generation and charges. If you have a task ID, query that task.
Temporary query error: retry the query with the same task ID; do not create a new generation.
delivery_exception: the generation charge is retained. Contact support to restore file access.