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.model_version": "<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.model_version": "<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.model_version': '<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.model_version' => '<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.model_version\": \"<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.model_version\": \"<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.model_version\": \"<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

Pin the delivery format of audio_url. Currently the only accepted value is "mp3".Omit it and you get the provider’s own file, in whatever format that provider produces. That is not a fixed format — it changes when a provider changes what it makes, and it changes when we route your request to a different provider to keep the service up. See Audio format.Send "mp3" and audio_url points at MP3. A source that is already MP3 is delivered as-is rather than re-encoded, so you never pay a second lossy pass for a file that was already right.If the conversion fails the task still succeeds — you get our copy of the source file, at our URL and our retention, in the source format. The response echoes back the audio_format you sent either way, because that field records the request rather than the outcome; read Content-Type to know what a file actually is.Applies to task types that return audio. A lyrics task has no audio_url, so the field changes nothing about what you receive — it is still accepted and still echoed back.Any other value is rejected with invalid_audio_format before any credits are charged. The field as a whole can also be refused with audio_format_unavailable, which means conversion is switched off on our side rather than anything being wrong with your request; omit the field to receive the provider’s original 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.

All three Suno modes also accept the model version:

string

default:"v6"

Suno model to generate with: "v6" (the default), "v5.5" or "v5". Suno retired v5.5 and v5 on 2026-09-09; both are still accepted for backward compatibility and generate with V6. Values are case-sensitive, and any other value is rejected with a 400 before any credits are charged. To use the default, omit the field; null is rejected. See Model version.

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

The delivery format this task was created with — the value you sent, or null if you omitted it. null means audio_url points at the provider’s own file, whose format is not fixed.

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.model_version": "<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.model_version": "<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.model_version': '<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.model_version' => '<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.model_version\": \"<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.model_version\": \"<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.model_version\": \"<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