GET

api

task

{taskId}

Get Task

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

{
  "code": 123,
  "data": {
    "task_id": "<string>",
    "model": "<string>",
    "type": "<string>",
    "status": "<string>",
    "credits_cost": 123,
    "input": {},
    "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

taskId

string

required

The task ID returned from the Create Task endpoint.

Headers

x-api-key

string

required

Your API key.

Response

code

number

HTTP status code (200 on success).

data

object

task_id

string

The unique task identifier.

model

string

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

type

string

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

status

string

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

credits_cost

number

Credits charged (or frozen) for this task.

input

object

The original input parameters submitted with the task.

output

object | null

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

error

string | null

Error message if the task failed. null otherwise.

created_at

string

ISO 8601 timestamp of task creation.

completed_at

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

Output format

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

output.task_type

string

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

output.status

string

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

output.progress

string | null

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

output.fail_reason

string | null

Reason for failure, if any.

output.result

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 (MP3)
`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://cdn1.suno.ai/clip-id-1.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://cdn1.suno.ai/clip-id-2.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 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

"output": {
  "task_type": "upload",
  "status": "completed",
  "progress": "100%",
  "fail_reason": null,
  "result": {
    "id": "uploaded-clip-id",
    "audio_url": "https://cdn1.suno.ai/uploaded-clip-id.mp3"
  }
}

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

"output": {
  "task_type": "concat",
  "status": "completed",
  "progress": "100%",
  "fail_reason": null,
  "result": {
    "id": "concat-clip-id",
    "audio_url": "https://cdn1.suno.ai/concat-clip-id.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://cdn1.suno.ai/clip-id-1.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": "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)

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 BalanceCheck your current credit balance

Get Task

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

{
  "code": 123,
  "data": {
    "task_id": "<string>",
    "model": "<string>",
    "type": "<string>",
    "status": "<string>",
    "credits_cost": 123,
    "input": {},
    "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

​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

Output format

Output by task type

Example responses

Task in progress

Task completed (music)

Task failed

Polling strategy

Polling example

Errors