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": {},
  "audio_format": "<string>",
  "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": {},
    "audio_format": "<string>",
    "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: {},
    audio_format: '<string>',
    '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' => [
        
    ],
    'audio_format' => '<string>',
    '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  \"audio_format\": \"<string>\",\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  \"audio_format\": \"<string>\",\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  \"audio_format\": \"<string>\",\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>",
    "audio_format": {}
  }
}

Create Task

Submit a new task to an AI model. The task is processed asynchronously — use the Get Task endpoint to poll for results. Sunor validates the JSON body, model, task type, and model-specific input before freezing credits, inserting a task, or calling an upstream provider. Invalid requests therefore fail without creating a task or changing the credit balance.

Request

POST /api/v1/task

Headers

string

required

Your API key.

string

required

Must be application/json.

Body parameters

string

required

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

string

required

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

object

required

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

string

Delivery format for the finished audio. Currently the only accepted value is "mp3".Omit it and audio_url points at the file exactly as the provider produced it — which is what every task did before this field existed. Today that is Opus audio in an MP4 container, served with an .m4a extension.Set it to "mp3" and we convert the audio before the task reports success, and audio_url points at the MP3. There is no extra charge, and no second request to make.Two things worth knowing:

A task that asks for conversion settles slightly later. The conversion runs before the task is reported complete, so expect one or two more polls than usual.
MP3 is re-encoded, not the original. The provider’s audio is already lossy, so converting it to MP3 is a second lossy step. We use 320 kbps to keep the added loss small, but it is not bit-for-bit the provider’s output. If your pipeline can consume the original, omitting this field gives you the better-quality file.

Sunor validates the documented model/task fields before charging credits or submitting to a provider. Extra root or input properties are accepted for backward/forward compatibility, but they are not interpreted as provider controls unless a request variant explicitly prohibits them. Use documented fields for provider behavior.

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.

string

required

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

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.

string

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

string

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

string

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

boolean

default:"false"

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

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.

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.

number

Timestamp in seconds to continue from.

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.

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

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

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

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

Response headers

Header	Description
`X-Request-Id`	Correlation identifier for this request. Log it with failures and support requests.
`X-RateLimit-Remaining`	Requests remaining in the current API-key window after authentication.

number

HTTP status code (202 on success).

object

string

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

string

The task type that was submitted.

string

Initial status, always "pending".

number

Number of credits frozen for this task.

string

ISO 8601 timestamp of when the task was created.

string | null

Echo of the accepted delivery format, or null if none was requested. Check it if you passed audio_format: a misspelled field name is ignored and shows up here as null, whereas a correctly spelled one is either accepted or rejected outright with invalid_audio_format / audio_format_unavailable. So null here means “we did not take your request”, not “it failed”.

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

Errors retain the numeric code and human-readable message, and also include a stable machine-readable error_code. See Error Codes for the full list.

Status	Representative `error_code`	Description
`400`	`invalid_json`, `invalid_request_body`, `missing_required_fields`, `invalid_model`, `unsupported_task_type`, `invalid_task_input`	Malformed request or invalid model/task input
`401`	`missing_api_key`, `invalid_api_key`	Missing or invalid API key
`402`	`insufficient_credits`	Insufficient credits
`403`	`account_suspended`	Account cannot create tasks
`429`	`rate_limited`	Rate limit exceeded
`500`	`internal_error`	Internal server error
`502`	`upstream_provider_error`	Upstream model provider error

Task creation does not currently support Idempotency-Key. If a network failure or uncertain 5xx leaves the create outcome unknown, do not automatically submit the same payload again. If a task_id was returned, poll that task instead.

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": {},
  "audio_format": "<string>",
  "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": {},
    "audio_format": "<string>",
    "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: {},
    audio_format: '<string>',
    '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' => [
        
    ],
    'audio_format' => '<string>',
    '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  \"audio_format\": \"<string>\",\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  \"audio_format\": \"<string>\",\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  \"audio_format\": \"<string>\",\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>",
    "audio_format": {}
  }
}

​Create Task

​Request

​Headers

​Body parameters

​Task types and input schemas

​music — Generate music

​lyrics — Generate lyrics

​upload — Upload audio

​concat — Concatenate clips

​Response

​Response headers

​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

Response headers

Code examples

Errors