POST

api

task

Create Task

curl --request POST \
  --url https://sunor.cc/api/v1/task \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "model": "<string>",
  "task_type": "<string>",
  "input": {},
  "input.prompt": "<string>",
  "input.url": "<string>",
  "input.clip_id": "<string>"
}
'

import requests

url = "https://sunor.cc/api/v1/task"

payload = {
    "model": "<string>",
    "task_type": "<string>",
    "input": {},
    "input.prompt": "<string>",
    "input.url": "<string>",
    "input.clip_id": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    model: '<string>',
    task_type: '<string>',
    input: {},
    'input.prompt': '<string>',
    'input.url': '<string>',
    'input.clip_id': '<string>'
  })
};

fetch('https://sunor.cc/api/v1/task', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => '<string>',
    'task_type' => '<string>',
    'input' => [
        
    ],
    'input.prompt' => '<string>',
    'input.url' => '<string>',
    'input.clip_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: <content-type>",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sunor.cc/api/v1/task"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"task_type\": \"<string>\",\n  \"input\": {},\n  \"input.prompt\": \"<string>\",\n  \"input.url\": \"<string>\",\n  \"input.clip_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<x-api-key>")
	req.Header.Add("Content-Type", "<content-type>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sunor.cc/api/v1/task")
  .header("x-api-key", "<x-api-key>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"model\": \"<string>\",\n  \"task_type\": \"<string>\",\n  \"input\": {},\n  \"input.prompt\": \"<string>\",\n  \"input.url\": \"<string>\",\n  \"input.clip_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sunor.cc/api/v1/task")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"model\": \"<string>\",\n  \"task_type\": \"<string>\",\n  \"input\": {},\n  \"input.prompt\": \"<string>\",\n  \"input.url\": \"<string>\",\n  \"input.clip_id\": \"<string>\"\n}"

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

{
  "code": 123,
  "data": {
    "task_id": "<string>",
    "type": "<string>",
    "status": "<string>",
    "credits_charged": 123,
    "created_at": "<string>"
  }
}

Create Task

Submit a new task to an AI model. The task is processed asynchronously — use the Get Task endpoint to poll for results.

Request

POST /api/v1/task

Headers

x-api-key

string

required

Your API key.

Content-Type

string

required

Must be application/json.

Body parameters

model

string

required

The AI model to use. One of "suno" or "udio". See the Suno and Udio model pages for capabilities and pricing.

task_type

string

required

The type of task to create. Suno supports: "music", "lyrics", "upload", "concat". Udio supports "music" only.

input

object

required

Task-specific input parameters. See the sections below for each task type.

Task types and input schemas

`music` — Generate music

The music task supports three modes depending on which input fields you provide.

Input fields differ by model. The examples below show Suno input shape (using gpt_description_prompt, make_instrumental, etc.). Udio uses a different field set — see the Udio model page for the Udio-specific shape. Mixing them produces a 400 validation error.

Inspiration Mode
Custom Mode
Continuation Mode
Udio

Generate music from a natural language description. The AI interprets your prompt and creates lyrics, melody, and arrangement.

input.gpt_description_prompt

string

required

A natural language description of the music you want (e.g., “A chill lo-fi beat for studying”).

input.make_instrumental

boolean

default:"false"

Set to true to generate instrumental music without vocals.

{
  "model": "suno",
  "task_type": "music",
  "input": {
    "gpt_description_prompt": "A cheerful acoustic guitar song about summer",
    "make_instrumental": false
  }
}

Provide your own lyrics and/or style tags for precise control over the output. For a style-driven instrumental, omit prompt and set make_instrumental: true.

input.prompt

string

The lyrics for the song. Use standard song structure notation like [Verse], [Chorus], etc. Omit (or leave empty) for an instrumental.

input.tags

string

Comma-separated style/genre tags (e.g., "pop, upbeat, female vocals").

input.negative_tags

string

Comma-separated tags for styles to avoid (e.g., "heavy metal, screaming").

input.make_instrumental

boolean

default:"false"

Set to true to generate an instrumental with no vocals. Combine with tags (and no prompt) for a style-driven instrumental.

input.title

string

Title of the song.

Provide at least one of prompt or tags. A music request with no prompt, tags, or gpt_description_prompt is rejected with a 400.

{
  "model": "suno",
  "task_type": "music",
  "input": {
    "prompt": "[Verse]\nWalking down the sunlit road\nFeeling light without a load\n\n[Chorus]\nOh summer days, carry me away",
    "tags": "pop, acoustic, upbeat",
    "title": "Summer Days"
  }
}

Style-driven instrumental (no lyrics):

{
  "model": "suno",
  "task_type": "music",
  "input": {
    "tags": "lofi, jazz piano, rain, mellow",
    "make_instrumental": true,
    "title": "Late Night Study"
  }
}

Extend an existing music clip from a specific timestamp.

input.continue_clip_id

string

required

The clip ID to continue from — from a previous music task output, or from an uploaded audio clip (the upload task) to extend your own audio into a full song.

input.continue_at

number

Timestamp in seconds to continue from.

input.prompt

string

Additional lyrics or instructions for the continuation.

{
  "model": "suno",
  "task_type": "music",
  "input": {
    "continue_clip_id": "abc123-clip-id",
    "continue_at": 30,
    "prompt": "[Chorus]\nKeep the music playing on"
  }
}

Udio uses a single prompt field for the style description. See the Udio model page for full options including lyrics, tags, lyrics_type, and seed.

input.prompt

string

required

Short style/mood description (e.g., “lofi hip hop, chill, rainy night, jazz piano”). Udio’s GPT layer expands it into full prompt + lyrics.

{
  "model": "udio",
  "task_type": "music",
  "input": {
    "prompt": "lofi hip hop, chill, rainy night, jazz piano"
  }
}

`lyrics` — Generate lyrics

input.prompt

string

required

A description of the lyrics you want (e.g., “A love song about the ocean at sunset”).

{
  "model": "suno",
  "task_type": "lyrics",
  "input": {
    "prompt": "A love song about the ocean at sunset"
  }
}

`upload` — Upload audio

input.url

string

required

A publicly accessible URL of the audio file to upload.

{
  "model": "suno",
  "task_type": "upload",
  "input": {
    "url": "https://example.com/my-audio.mp3"
  }
}

The upload returns a clip id (at output.result[0].id). Pass it as continue_clip_id in a music task to extend your uploaded audio into a full song (see the Continuation Mode tab under the music task). Generating a new song in a different style from an uploaded reference (an “audio cover”) is not currently supported.

`concat` — Concatenate clips

input.clip_id

string

required

The clip ID to concatenate (obtained from a previous music task output).

{
  "model": "suno",
  "task_type": "concat",
  "input": {
    "clip_id": "abc123-clip-id"
  }
}

Response

code

number

HTTP status code (202 on success).

data

object

task_id

string

Unique identifier for the created task. Use this to poll for results.

type

string

The task type that was submitted.

status

string

Initial status, always "pending".

credits_charged

number

Number of credits frozen for this task.

created_at

string

ISO 8601 timestamp of when the task was created.

202

{
  "code": 202,
  "data": {
    "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type": "music",
    "status": "pending",
    "credits_charged": 10,
    "created_at": "2025-01-15T10:30:00.000Z"
  }
}

Code examples

curl -X POST https://sunor.cc/api/v1/task \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "model": "suno",
    "task_type": "music",
    "input": {
      "gpt_description_prompt": "A cheerful acoustic guitar song about summer",
      "make_instrumental": false
    }
  }'

import requests

response = requests.post(
    "https://sunor.cc/api/v1/task",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY",
    },
    json={
        "model": "suno",
        "task_type": "music",
        "input": {
            "gpt_description_prompt": "A cheerful acoustic guitar song about summer",
            "make_instrumental": False,
        },
    },
)

data = response.json()
task_id = data["data"]["task_id"]
print(f"Task created: {task_id}")

const response = await fetch("https://sunor.cc/api/v1/task", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    model: "suno",
    task_type: "music",
    input: {
      gpt_description_prompt: "A cheerful acoustic guitar song about summer",
      make_instrumental: false,
    },
  }),
});

const data = await response.json();
console.log("Task created:", data.data.task_id);

Errors

Status	Description
`400`	Missing required fields (`model`, `task_type`, or `input`) or invalid task type
`401`	Missing or invalid API key
`402`	Insufficient credits
`429`	Rate limit exceeded
`500`	Internal server error

Get TaskRetrieve the status and output of a task

Create Task

curl --request POST \
  --url https://sunor.cc/api/v1/task \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "model": "<string>",
  "task_type": "<string>",
  "input": {},
  "input.prompt": "<string>",
  "input.url": "<string>",
  "input.clip_id": "<string>"
}
'

import requests

url = "https://sunor.cc/api/v1/task"

payload = {
    "model": "<string>",
    "task_type": "<string>",
    "input": {},
    "input.prompt": "<string>",
    "input.url": "<string>",
    "input.clip_id": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    model: '<string>',
    task_type: '<string>',
    input: {},
    'input.prompt': '<string>',
    'input.url': '<string>',
    'input.clip_id': '<string>'
  })
};

fetch('https://sunor.cc/api/v1/task', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => '<string>',
    'task_type' => '<string>',
    'input' => [
        
    ],
    'input.prompt' => '<string>',
    'input.url' => '<string>',
    'input.clip_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: <content-type>",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sunor.cc/api/v1/task"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"task_type\": \"<string>\",\n  \"input\": {},\n  \"input.prompt\": \"<string>\",\n  \"input.url\": \"<string>\",\n  \"input.clip_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<x-api-key>")
	req.Header.Add("Content-Type", "<content-type>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sunor.cc/api/v1/task")
  .header("x-api-key", "<x-api-key>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"model\": \"<string>\",\n  \"task_type\": \"<string>\",\n  \"input\": {},\n  \"input.prompt\": \"<string>\",\n  \"input.url\": \"<string>\",\n  \"input.clip_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sunor.cc/api/v1/task")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"model\": \"<string>\",\n  \"task_type\": \"<string>\",\n  \"input\": {},\n  \"input.prompt\": \"<string>\",\n  \"input.url\": \"<string>\",\n  \"input.clip_id\": \"<string>\"\n}"

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

{
  "code": 123,
  "data": {
    "task_id": "<string>",
    "type": "<string>",
    "status": "<string>",
    "credits_charged": 123,
    "created_at": "<string>"
  }
}

​Create Task

​Request

​Headers

​Body parameters

​Task types and input schemas

​music — Generate music

​lyrics — Generate lyrics

​upload — Upload audio

​concat — Concatenate clips

​Response

​Code examples

​Errors

Create Task

Request

Headers

Body parameters

Task types and input schemas

`music` — Generate music

`lyrics` — Generate lyrics

`upload` — Upload audio

`concat` — Concatenate clips

Response

Code examples

Errors