Query Music Detail

Query Music Generation Detail

curl --request GET \
  --url https://api.poyo.ai/api/generate/detail/music \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.poyo.ai/api/generate/detail/music', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.poyo.ai/api/generate/detail/music",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.poyo.ai/api/generate/detail/music"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.poyo.ai/api/generate/detail/music")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "credits_amount": 10,
    "files": [
      {
        "audio_id": "62e4542a-73be-44e1-b397-7716ee7505c6",
        "audio_url": "https://storage.poyo.ai/audio/8FDN1I7M7Q68DDG8/20251125113627_QIivN2_tmphb8rgpeb_audio_62e4542a-73be-44e1-b397-7716ee7505c6.mp3",
        "image_url": "https://storage.poyo.ai/audio/8FDN1I7M7Q68DDG8/20251125113628_4DfWp6_tmpz72j05o5_cover_62e4542a-73be-44e1-b397-7716ee7505c6.jpeg",
        "title": "Peaceful Piano Meditation",
        "tags": "Classical",
        "duration": 240,
        "prompt": ""
      },
      {
        "audio_id": "8e755734-a840-4c13-beac-b9f1044979ca",
        "audio_url": "https://storage.poyo.ai/audio/8FDN1I7M7Q68DDG8/20251125113630_x7VTpV_tmpvsijwxa6_audio_8e755734-a840-4c13-beac-b9f1044979ca.mp3",
        "image_url": "https://storage.poyo.ai/audio/8FDN1I7M7Q68DDG8/20251125113631_3MTe5V_tmp98wzcx2m_cover_8e755734-a840-4c13-beac-b9f1044979ca.jpeg",
        "title": "Peaceful Piano Meditation",
        "tags": "Classical",
        "duration": 130,
        "prompt": ""
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

GET

api

generate

detail

music

Query Music Generation Detail

curl --request GET \
  --url https://api.poyo.ai/api/generate/detail/music \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.poyo.ai/api/generate/detail/music', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.poyo.ai/api/generate/detail/music",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.poyo.ai/api/generate/detail/music"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.poyo.ai/api/generate/detail/music")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "credits_amount": 10,
    "files": [
      {
        "audio_id": "62e4542a-73be-44e1-b397-7716ee7505c6",
        "audio_url": "https://storage.poyo.ai/audio/8FDN1I7M7Q68DDG8/20251125113627_QIivN2_tmphb8rgpeb_audio_62e4542a-73be-44e1-b397-7716ee7505c6.mp3",
        "image_url": "https://storage.poyo.ai/audio/8FDN1I7M7Q68DDG8/20251125113628_4DfWp6_tmpz72j05o5_cover_62e4542a-73be-44e1-b397-7716ee7505c6.jpeg",
        "title": "Peaceful Piano Meditation",
        "tags": "Classical",
        "duration": 240,
        "prompt": ""
      },
      {
        "audio_id": "8e755734-a840-4c13-beac-b9f1044979ca",
        "audio_url": "https://storage.poyo.ai/audio/8FDN1I7M7Q68DDG8/20251125113630_x7VTpV_tmpvsijwxa6_audio_8e755734-a840-4c13-beac-b9f1044979ca.mp3",
        "image_url": "https://storage.poyo.ai/audio/8FDN1I7M7Q68DDG8/20251125113631_3MTe5V_tmp98wzcx2m_cover_8e755734-a840-4c13-beac-b9f1044979ca.jpeg",
        "title": "Peaceful Piano Meditation",
        "tags": "Classical",
        "duration": 130,
        "prompt": ""
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

Usage Guide

All POST submission requests in the Music Series can query their results through this endpoint. Different models return different response fields.

Parameter Details

task_id (required): The unique task identifier returned from the music generation submission endpoint

Developer Notes

Poll this endpoint to check task completion status
The files array is normally empty until completion. Voice tasks may expose intermediate voice_status or validate_info while still running.
When a task fails, check the error_message field for details
Multiple audio files may be returned for a single task as variations are generated
minimax-music-2.6 detail responses return audio_id, audio_url, title, duration, and prompt
credits_amount is returned at the task level, alongside task_id, status, and files. It is not repeated inside each item in files.

Response Fields (task data)

Field	Type	Description
`task_id`	string	Unique task identifier
`status`	string	Task status: `not_started`, `running`, `finished`, `failed`
`credits_amount`	number	Credits charged for the task
`progress`	number	Current task progress from 0 to 100
`files`	array	Generated music result files or task-specific result objects
`created_time`	string	ISO 8601 timestamp when the task was created
`error_message`	string \| null	Error message when the task failed

Response Fields (files data)

The files array content varies depending on which model created the task.

Model	Field	Type	Description
`generate-music`, `extend-music`, `upload-and-cover-audio`, `upload-and-extend-audio`, `add-instrumental`, `add-vocals`, `replace-section`	`audio_id`	string	Unique identifier for the audio file
`generate-music`, `extend-music`, `upload-and-cover-audio`, `upload-and-extend-audio`, `add-instrumental`, `add-vocals`, `replace-section`	`audio_url`	string	Direct download URL for the audio file
`generate-music`, `extend-music`, `upload-and-cover-audio`, `upload-and-extend-audio`, `add-instrumental`, `add-vocals`, `replace-section`	`image_url`	string	Cover image URL
`generate-music`, `extend-music`, `upload-and-cover-audio`, `upload-and-extend-audio`, `add-instrumental`, `add-vocals`, `replace-section`	`title`	string	Track title
`generate-music`, `extend-music`, `upload-and-cover-audio`, `upload-and-extend-audio`, `add-instrumental`, `add-vocals`, `replace-section`	`tags`	string	Style tags
`generate-music`, `extend-music`, `upload-and-cover-audio`, `upload-and-extend-audio`, `add-instrumental`, `add-vocals`, `replace-section`	`duration`	number	Audio duration in seconds
`generate-music`, `extend-music`, `upload-and-cover-audio`, `upload-and-extend-audio`, `add-instrumental`, `add-vocals`, `replace-section`	`prompt`	string	Generation prompt used
`generate-mashup`, `generate-sounds`	`audio_id`, `audio_url`, `stream_audio_url`, `image_url`, `title`, `tags`, `prompt`, `duration`	mixed	Generated audio fields when available
Standard music results	`model_name`, `source_audio_url`, `source_image_url`, `source_stream_audio_url`	string	Model and derivative source metadata when available
`minimax-music-2.6`	`audio_id`	string	Unique identifier for the generated audio file
`minimax-music-2.6`	`audio_url`	string	Direct download URL for the generated audio file
`minimax-music-2.6`	`title`	string	Track title derived from the submitted prompt
`minimax-music-2.6`	`duration`	number	Audio duration in seconds
`minimax-music-2.6`	`prompt`	string	Original prompt used for generation
`get-timestamped-lyrics`	`timestampe_lyrics`	string	Lyrics with timestamps
`generate-lyrics`	`title`	string	Lyrics title
`generate-lyrics`	`text`	string	Complete lyrics content
`boost-music-style`	`style`	string	Enhanced music style
`convert-to-wav`	`wav_url`	string	URL to converted WAV file
`separate-vocals`	`separate_vocals`	object	Separated audio URLs. See details
`upload-and-separate-vocals`	`vocal_removal`	object	Separated stem URLs. See details
`stem-split`	`stem_split`	object	Full stem separation URLs. See details
`generate-music-cover`	`generate_cover`	array	Generated cover images. See details
`generate-persona`	`persona_id`	string	Generated persona identifier
`create-music-video`	`video_url`	string	Generated video URL
`suno-voice-validate`, `suno-voice-regenerate`	`validate_info`, `voice_status`	string \| null	Verification phrase and current validation state
`suno-voice-generate`	`voice_id`, `voice_status`	string \| null	Generated voice identifier and creation state
`suno-voice-check`	`is_available`	boolean	Whether the generated voice can currently be used
Suno Voice tasks	`error_message`, `error_code`	string/number \| null	Structured error details when available

Voice Generate result example

{"task_id":"POYO_VOICE_GENERATE_TASK","status":"finished","credits_amount":0,"progress":100,"files":[{"voice_status":"success","voice_id":"voice_abc123"}],"error_message":null}

Voice Validate or Regenerate result example

{"task_id":"POYO_VOICE_VALIDATE_TASK","status":"finished","credits_amount":0,"progress":100,"files":[{"voice_status":"wait_validating","validate_info":"Read the displayed verification phrase clearly."}],"error_message":null}

Voice Check result example

{"task_id":"POYO_VOICE_CHECK_TASK","status":"finished","credits_amount":0,"progress":100,"files":[{"is_available":true}],"error_message":null}

JSON Field Details

separate-vocals

separate_vocals fields:

vocal_url - URL to the extracted vocal track
instrumental_url - URL to the instrumental track

upload-and-separate-vocals

vocal_removal fields:

bass - URL to the bass track
drums - URL to the drums track
piano - URL to the piano track
guitar - URL to the guitar track
vocals - URL to the vocals track
other - URL to other audio elements

stem-split

stem_split fields:

backing_vocals_url - URL to backing vocals
bass_url - URL to bass track
brass_url - URL to brass instruments
drums_url - URL to drums track
fx_url - URL to sound effects
guitar_url - URL to guitar track
keyboard_url - URL to keyboard track
percussion_url - URL to percussion track
strings_url - URL to strings track
synth_url - URL to synthesizer track
vocal_url - URL to main vocals
woodwinds_url - URL to woodwinds track
piano_url - URL to piano track

generate-music-cover

generate_cover is a JSON array containing cover image objects:

file_url - URL to the generated cover image
file_type - File type (for example, image)

Authorizations

Authorization

string

header

required

All API endpoints require Bearer Token authentication

Get your API Key:

Visit the API Key Management Page to get your API Key

Add it to the request header:

Authorization: Bearer PoYo_API_KEY

Query Parameters

task_id

string

required

Unique task identifier returned from the music generation submission endpoint.

Response

200 - application/json

Task detail retrieved successfully

code

integer

required

HTTP status code

Example:

200

data

object

required

Show child attributes

Overview

Image Model

Video Model

Music Model

Chat Model

3D Model

Task Management

Query Music Detail

Usage Guide

Parameter Details

Developer Notes

Response Fields (task data)

Response Fields (files data)

Voice Generate result example

Voice Validate or Regenerate result example

Voice Check result example

JSON Field Details

separate-vocals

upload-and-separate-vocals

stem-split

generate-music-cover

Authorizations

Query Parameters

Response

​Usage Guide

​Parameter Details

​Developer Notes

​Response Fields (task data)

​Response Fields (files data)

​Voice Generate result example

​Voice Validate or Regenerate result example

​Voice Check result example

​JSON Field Details

​separate-vocals

​upload-and-separate-vocals

​stem-split

​generate-music-cover

Authorizations

Query Parameters

Response

Usage Guide

Parameter Details

Developer Notes

Response Fields (task data)

Response Fields (files data)

Voice Generate result example

Voice Validate or Regenerate result example

Voice Check result example

JSON Field Details

separate-vocals

upload-and-separate-vocals

stem-split

generate-music-cover