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>"
}
'

{
  "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 style tags for precise control over the output.

input.prompt

string

required

The lyrics for the song. Use standard song structure notation like [Verse], [Chorus], etc.

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.title

string

Title of the song.

{
  "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"
  }
}

Extend an existing music clip from a specific timestamp.

input.continue_clip_id

string

required

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

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"
  }
}

`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
    }
  }'

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>"
}
'

{
  "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