Create Task

Submit a new AI generation task

POST https://sunor.cc/api/v1/task

Create Task

cURL

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

200

{
  "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. Currently only "suno" is supported.

task_type · string · required

The type of task to create. One of: "music", "lyrics", "upload", "concat".

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.

Inspiration Mode

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.

input.mv · string · default: "chirp-v4"

Model version. Options: "chirp-v3-5", "chirp-v4".

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

Custom Mode

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.

input.mv · string · default: "chirp-v4"

Model version. Options: "chirp-v3-5", "chirp-v4".

{
  "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",
    "mv": "chirp-v4"
  }
}

Continuation Mode

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.

input.mv · string · default: "chirp-v4"

Model version. Options: "chirp-v3-5", "chirp-v4".

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

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

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,
      "mv": "chirp-v4"
    }
  }'

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
500	Internal server error