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.

Create an API key: sign in to PoYo, open Dashboard → API Key at poyo.ai/dashboard/api-key, and click to create a key.

Add it to the request header:

Authorization: Bearer YOUR_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

enum<integer>

required

Business status code. 200 means success; any other value means the request failed. Always check this field: some validation errors return HTTP 200 with code: 400 in the body.

200: Success
400: Invalid request parameters
401: Missing or invalid API key
402: Insufficient credits
403: Permission denied
404: Resource not found
408: Request timeout
429: Rate limit exceeded
500: Internal server error
502: Upstream service error
503: Service unavailable

See Error Codes for details.

Available options:

200,

400,

401,

402,

403,

404,

408,

429,

500,

502,

503

Example:

200

data

object

required

Show child attributes

Overview

Task Management

File Management

Account Management

Security & Best Practices

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