GET

api

task

{taskId}

Get Task

curl --request GET \
  --url https://sunor.cc/api/v1/task/{taskId} \
  --header 'x-api-key: <x-api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<x-api-key>'}};

fetch('https://sunor.cc/api/v1/task/{taskId}', 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://sunor.cc/api/v1/task/{taskId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <x-api-key>"
  ],
]);

$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://sunor.cc/api/v1/task/{taskId}"

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

	req.Header.Add("x-api-key", "<x-api-key>")

	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://sunor.cc/api/v1/task/{taskId}")

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

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<x-api-key>'

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

{
  "code": 123,
  "data": {
    "task_id": "<string>",
    "model": "<string>",
    "type": "<string>",
    "status": "<string>",
    "credits_cost": 123,
    "input": {},
    "audio_format": {},
    "output": {},
    "error": {},
    "created_at": "<string>",
    "completed_at": {}
  },
  "output.task_type": "<string>",
  "output.status": "<string>",
  "output.progress": {},
  "output.fail_reason": {},
  "output.result": [
    {}
  ]
}

Get Task

Retrieve the current status, input, and output of a previously created task. If the task is still in progress, sunor will live-poll the upstream provider and return the latest status.

Request

GET /api/v1/task/{taskId}

Path parameters

string

required

The task ID returned from the Create Task endpoint.

Headers

string

required

Your API key.

Response

number

HTTP status code (200 on success).

object

string

The unique task identifier.

string

The model used (e.g., "suno").

string

The task type ("music", "lyrics", "upload", or "concat").

string

Current task status. One of: "pending", "running", "success", "failure", "timeout".

number

Credits charged (or frozen) for this task.

object

The original input parameters submitted with the task.

string | null

The delivery format this task was created with, or null for the provider’s original. When set to "mp3", audio_url points at a converted copy. See audio_format on Create Task.

object | null

The task output. null while the task is still processing. Contains model-specific results on completion.

string | null

Error message if the task failed. null otherwise.

string

ISO 8601 timestamp of task creation.

string | null

ISO 8601 timestamp of task completion. null if not yet completed.

Status values

Status	Description
`pending`	Task has been submitted and is waiting to be processed
`running`	Task is actively being processed by the upstream provider
`success`	Task completed successfully. Output is available
`failure`	Task failed. Check the `error` field for details. Credits are refunded
`timeout`	Task timed out. Credits are refunded

Audio URL lifetime

audio_url is valid for 7 days after the task completes. After that it returns 404 permanently. If you need the audio for longer, download and store it yourself.

Cover art (image_url, image_large_url) is served by the model provider and is not covered by this window.

Contract

The fields listed on this page are the response contract, and they hold across provider changes: every one of them has been present on every clip we have returned. output.result also carries additional fields from the upstream model provider. Those are passed through as-is. They are not part of the contract, they differ between providers, and they may appear or disappear without notice — build against the documented fields.

Audio format

By default audio_url points at the file exactly as the provider produced it. Today that is Opus audio in an MP4 container, served with an .m4a extension. That combination is worth knowing about, because .m4a normally implies AAC and not every client handles Opus in this container — Apple’s CoreAudio, which every iOS and macOS app sits on, cannot decode it at all. If your pipeline is affected, pass audio_format: "mp3" when creating the task and audio_url will point at an MP3 instead. Derive the concrete format from the response’s Content-Type rather than from the URL’s extension or from the format the provider was using the last time you looked.

Output format

The output field structure depends on the task type. All outputs share a common wrapper:

string

The task type ("music", "lyrics", "upload", or "concat").

string

Internal processing status: "queued", "processing", "completed", or "failed".

string | null

Processing progress (e.g., "50%", "100%").

string | null

Reason for failure, if any.

array | object | null

The task-specific result. Shape varies by task type (see below).

Output by task type

Music
Lyrics
Upload
Concat

result is an array of clip objects. Each music generation typically returns one or more clip variations.

Field	Type	Description
`id`	`string`	Unique clip identifier. Use this for continuation or concat tasks
`audio_url`	`string`	URL to the generated audio file. Derive the format from the response’s `Content-Type` rather than assuming one. See Audio URL lifetime
`image_url`	`string`	URL to the generated cover art
`title`	`string`	Generated or provided song title
`metadata`	`object`	Additional info: `duration` (seconds), `tags`, `prompt`, etc.

"output": {
  "task_type": "music",
  "status": "completed",
  "progress": "100%",
  "fail_reason": null,
  "result": [
    {
      "id": "clip-id-1",
      "audio_url": "https://audio.sunor.cc/audio/6fdfdf84-43d5-4a63-90c4-340e678739b2/810509c7d9873364.m4a",
      "image_url": "https://cdn2.suno.ai/image_clip-id-1.jpeg",
      "title": "Summer Days",
      "metadata": {
        "duration": 120,
        "tags": "acoustic, cheerful, summer"
      }
    },
    {
      "id": "clip-id-2",
      "audio_url": "https://audio.sunor.cc/audio/6fdfdf84-43d5-4a63-90c4-340e678739b2/72683fa7bd9b4723.m4a",
      "image_url": "https://cdn2.suno.ai/image_clip-id-2.jpeg",
      "title": "Summer Days",
      "metadata": {
        "duration": 118,
        "tags": "acoustic, cheerful, summer"
      }
    }
  ]
}

result is an object containing the generated lyrics and title.

Field	Type	Description
`title`	`string`	Generated song title
`text`	`string`	Generated lyrics with structure tags (`[Verse]`, `[Chorus]`, etc.)

"output": {
  "task_type": "lyrics",
  "status": "completed",
  "progress": "100%",
  "fail_reason": null,
  "result": {
    "title": "Ocean Sunset",
    "text": "[Verse]\nWaves are crashing on the shore\nGolden light I can't ignore\n\n[Chorus]\nAt the edge of the sea\nYou and me, finally free"
  }
}

result is an object containing the uploaded clip information.

Field	Type	Description
`id`	`string`	Clip ID for the uploaded audio. Use this in other tasks
`audio_url`	`string`	URL to the uploaded audio. See Audio URL lifetime

"output": {
  "task_type": "upload",
  "status": "completed",
  "progress": "100%",
  "fail_reason": null,
  "result": {
    "id": "uploaded-clip-id",
    "audio_url": "https://audio.sunor.cc/audio/6fdfdf84-43d5-4a63-90c4-340e678739b2/a256638015d2e5f4.m4a"
  }
}

result is an object containing the concatenated clip.

Field	Type	Description
`id`	`string`	Clip ID for the concatenated audio
`audio_url`	`string`	URL to the concatenated audio file. See Audio URL lifetime

"output": {
  "task_type": "concat",
  "status": "completed",
  "progress": "100%",
  "fail_reason": null,
  "result": {
    "id": "concat-clip-id",
    "audio_url": "https://audio.sunor.cc/audio/6fdfdf84-43d5-4a63-90c4-340e678739b2/b5cdf870fc295ff7.m4a"
  }
}

Example responses

Task in progress

200

{
  "code": 200,
  "data": {
    "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "model": "suno",
    "type": "music",
    "status": "running",
    "credits_cost": 10,
    "input": {
      "gpt_description_prompt": "A cheerful acoustic guitar song about summer",
      "make_instrumental": false
    },
    "output": {
      "task_type": "music",
      "status": "processing",
      "progress": "50%",
      "fail_reason": null,
      "result": null
    },
    "error": null,
    "created_at": "2025-01-15T10:30:00.000Z",
    "completed_at": null
  }
}

Task completed (music)

200

{
  "code": 200,
  "data": {
    "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "model": "suno",
    "type": "music",
    "status": "success",
    "credits_cost": 10,
    "input": {
      "gpt_description_prompt": "A cheerful acoustic guitar song about summer",
      "make_instrumental": false
    },
    "output": {
      "task_type": "music",
      "status": "completed",
      "progress": "100%",
      "fail_reason": null,
      "result": [
        {
          "id": "clip-id-1",
          "audio_url": "https://audio.sunor.cc/audio/6fdfdf84-43d5-4a63-90c4-340e678739b2/810509c7d9873364.m4a",
          "image_url": "https://cdn2.suno.ai/image_clip-id-1.jpeg",
          "title": "Summer Days",
          "metadata": {
            "duration": 120,
            "tags": "acoustic, cheerful, summer"
          }
        }
      ]
    },
    "error": null,
    "created_at": "2025-01-15T10:30:00.000Z",
    "completed_at": "2025-01-15T10:32:15.000Z"
  }
}

Task failed

200

{
  "code": 200,
  "data": {
    "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "model": "suno",
    "type": "music",
    "status": "failure",
    "credits_cost": 10,
    "input": {
      "gpt_description_prompt": "A cheerful acoustic guitar song about summer"
    },
    "output": {
      "task_type": "music",
      "status": "failed",
      "progress": null,
      "fail_reason": "Upstream provider returned an error",
      "result": null
    },
    "error": "Upstream provider returned an error",
    "created_at": "2025-01-15T10:30:00.000Z",
    "completed_at": "2025-01-15T10:30:45.000Z"
  }
}

Polling strategy

Tasks typically take 30 seconds to 5 minutes to complete, depending on the task type and upstream provider load.

Poll the Get Task endpoint every 5-10 seconds until the status is "success", "failure", or "timeout". Avoid polling more frequently than once per second.

Polling example

import time
import requests

API_KEY = "YOUR_API_KEY"
TASK_ID = "f47ac10b-58cc-4372-a567-0e02b2c3d479"

while True:
    response = requests.get(
        f"https://sunor.cc/api/v1/task/{TASK_ID}",
        headers={"x-api-key": API_KEY},
    )
    data = response.json()["data"]
    status = data["status"]
    print(f"Status: {status}")

    if status in ("success", "failure", "timeout"):
        print("Result:", data["output"])
        break

    time.sleep(5)

const API_KEY = "YOUR_API_KEY";
const TASK_ID = "f47ac10b-58cc-4372-a567-0e02b2c3d479";

async function pollTask() {
  while (true) {
    const response = await fetch(
      `https://sunor.cc/api/v1/task/${TASK_ID}`,
      { headers: { "x-api-key": API_KEY } }
    );
    const { data } = await response.json();
    console.log("Status:", data.status);

    if (["success", "failure", "timeout"].includes(data.status)) {
      console.log("Result:", data.output);
      break;
    }

    await new Promise((r) => setTimeout(r, 5000));
  }
}

pollTask();

Errors

Status	Description
`401`	Missing or invalid API key
`404`	Task not found (invalid ID or task belongs to another user)
`429`	Rate limit exceeded
`500`	Internal server error

Get Task

curl --request GET \
  --url https://sunor.cc/api/v1/task/{taskId} \
  --header 'x-api-key: <x-api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<x-api-key>'}};

fetch('https://sunor.cc/api/v1/task/{taskId}', 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://sunor.cc/api/v1/task/{taskId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <x-api-key>"
  ],
]);

$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://sunor.cc/api/v1/task/{taskId}"

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

	req.Header.Add("x-api-key", "<x-api-key>")

	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://sunor.cc/api/v1/task/{taskId}")

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

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<x-api-key>'

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

{
  "code": 123,
  "data": {
    "task_id": "<string>",
    "model": "<string>",
    "type": "<string>",
    "status": "<string>",
    "credits_cost": 123,
    "input": {},
    "audio_format": {},
    "output": {},
    "error": {},
    "created_at": "<string>",
    "completed_at": {}
  },
  "output.task_type": "<string>",
  "output.status": "<string>",
  "output.progress": {},
  "output.fail_reason": {},
  "output.result": [
    {}
  ]
}

​Get Task

​Request

​Path parameters

​Headers

​Response

​Status values

​Audio URL lifetime

​Contract

​Audio format

​Output format

​Output by task type

​Example responses

​Task in progress

​Task completed (music)

​Task failed

​Polling strategy

​Polling example

​Errors

Get Task

Request

Path parameters

Headers

Response

Status values

Audio URL lifetime

Contract

Audio format

Output format

Output by task type

Example responses

Task in progress

Task completed (music)

Task failed

Polling strategy

Polling example

Errors