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": {},
    "error_code": {},
    "retryable": {},
    "retry_after_seconds": {},
    "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 — the value sent on the create request, or null if it was omitted. null means audio_url points at the provider’s own file, whose format is not fixed. See Audio format.

object | null

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

string | null

Human-readable message if the task failed. null otherwise. Prose — do not branch on it. It may be reworded at any time; branch on error_code.

string | null

Stable machine-readable classification of a failed task. null unless status is failure or timeout. One of content_moderation, invalid_task_input, rate_limited, upstream_provider_error — see Error Codes.

boolean | null

false means resending the same request is very unlikely to succeed — change the input, or surface it to a person. true means a later attempt may succeed; see Error Codes for which codes reverse on identical input and which need a wait first. null unless the task failed.

integer | null

Seconds to wait before retrying, when the provider states a concrete wait. 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. Branch on `error_code` / `retryable`; `error` is the human-readable reason. 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. That last clause is not hypothetical. Some of those fields exist on one provider and not at all on another: routing a request differently makes them vanish from every clip, with no other change on our side and no announcement. Two further things are worth knowing about them:

Where such a field lists alternate URLs for the same audio, and the clip’s own audio_url is one we serve, we remove any entry that still points at a provider’s own origin and remove the field entirely when no entry survives. What is left is served from our domain under the same retention as audio_url.
For any other clip that field is passed through untouched, provider origins included — a clip we could not store keeps upstream’s list verbatim, because editing a response we are not otherwise the source of would be worse than leaving it alone. Those URLs expire on the provider’s schedule, not ours, and some of them are streams a normal client cannot play. audio_url is the field to use; treat the alternates as informational at best.

If you have built on an undocumented field, treat it as something that can disappear between two consecutive requests.

Audio format

By default audio_url points at the file exactly as the provider produced it. That format is not fixed, and it has changed more than once. As of 2026-09-06 it is MP3, served with a .mp3 extension. Between 2026-08-29 and 2026-09-05 it was Opus in an MP4 container, served with an .m4a extension. It can change for two different reasons, and the second one is ours:

The provider changes what it produces — that is what happened on both dates above.
We route your request to a different provider. We run more than one, they do not all produce the same format, and we will move traffic between them to keep the service up. When that happens the default format changes with it, without notice and without any change on your side.

If your pipeline needs one specific format, pin it. Send audio_format: "mp3" when you create the task and audio_url will point at MP3 — we convert on our side when the source is something else, and skip the conversion when it is already MP3. Leaving the field out keeps today’s behaviour exactly: you get the provider’s own file, in whatever format that is. One case is worth knowing about. If the conversion fails we do not fail the task — you get our copy of the source file instead: our URL, our retention, the source format. A conversion that costs you the recording you paid for would be a bad trade for an optional convenience. The response still echoes back the audio_format you asked for, because that field records the request, not the outcome — so Content-Type remains the only reliable statement of what a file actually is. Every response carries it, and the paragraphs below explain why it is worth reading. Two more things follow, and both are worth building around rather than checking once:

Read the format from the response’s Content-Type. Not from the URL’s extension, and not from what the provider was serving the last time you looked. An .m4a extension in particular does not imply AAC.
Do not assume every container decodes on every platform. Apple’s CoreAudio — the API every iOS and macOS app sits on — cannot decode Opus in an MP4 container at all. If you target Apple platforms, branch on Content-Type and convert on your side when you receive something it cannot read.

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.mp3",
      "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.mp3",
      "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 array 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.mp3"
    }
  ]
}

result is an array 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.mp3"
    }
  ]
}

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.mp3",
          "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": "Generation failed and your credits were refunded. Please try again; if this keeps happening, contact support@sunor.cc.",
      "result": null
    },
    "error": "Generation failed and your credits were refunded. Please try again; if this keeps happening, contact support@sunor.cc.",
    "error_code": "upstream_provider_error",
    "retryable": true,
    "retry_after_seconds": null,
    "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": {},
    "error_code": {},
    "retryable": {},
    "retry_after_seconds": {},
    "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