> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunor.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Task

> Submit a new AI generation task

# Create Task

Submit a new task to an AI model. The task is processed asynchronously -- use the [Get Task](/api-reference/get-task) endpoint to poll for results.

## Request

```
POST /api/v1/task
```

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

### Body parameters

<ParamField body="model" type="string" required>
  The AI model to use. One of `"suno"` or `"udio"`. See the [Suno](/models/suno) and [Udio](/models/udio) model pages for capabilities and pricing.
</ParamField>

<ParamField body="task_type" type="string" required>
  The type of task to create. Suno supports: `"music"`, `"lyrics"`, `"upload"`, `"concat"`. Udio supports `"music"` only.
</ParamField>

<ParamField body="input" type="object" required>
  Task-specific input parameters. See the sections below for each task type.
</ParamField>

***

## Task types and input schemas

### `music` — Generate music

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

<Warning>
  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](/models/udio) for the Udio-specific shape. Mixing them produces a `400` validation error.
</Warning>

<Tabs>
  <Tab title="Inspiration Mode">
    Generate music from a natural language description. The AI interprets your prompt and creates lyrics, melody, and arrangement.

    <ParamField body="input.gpt_description_prompt" type="string" required>
      A natural language description of the music you want (e.g., "A chill lo-fi beat for studying").
    </ParamField>

    <ParamField body="input.make_instrumental" type="boolean" default="false">
      Set to `true` to generate instrumental music without vocals.
    </ParamField>

    ```json theme={null}
    {
      "model": "suno",
      "task_type": "music",
      "input": {
        "gpt_description_prompt": "A cheerful acoustic guitar song about summer",
        "make_instrumental": false
      }
    }
    ```
  </Tab>

  <Tab title="Custom Mode">
    Provide your own lyrics and style tags for precise control over the output.

    <ParamField body="input.prompt" type="string" required>
      The lyrics for the song. Use standard song structure notation like `[Verse]`, `[Chorus]`, etc.
    </ParamField>

    <ParamField body="input.tags" type="string">
      Comma-separated style/genre tags (e.g., `"pop, upbeat, female vocals"`).
    </ParamField>

    <ParamField body="input.negative_tags" type="string">
      Comma-separated tags for styles to avoid (e.g., `"heavy metal, screaming"`).
    </ParamField>

    <ParamField body="input.title" type="string">
      Title of the song.
    </ParamField>

    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Tab>

  <Tab title="Continuation Mode">
    Extend an existing music clip from a specific timestamp.

    <ParamField body="input.continue_clip_id" type="string" required>
      The clip ID to continue from (obtained from a previous music task output).
    </ParamField>

    <ParamField body="input.continue_at" type="number">
      Timestamp in seconds to continue from.
    </ParamField>

    <ParamField body="input.prompt" type="string">
      Additional lyrics or instructions for the continuation.
    </ParamField>

    ```json theme={null}
    {
      "model": "suno",
      "task_type": "music",
      "input": {
        "continue_clip_id": "abc123-clip-id",
        "continue_at": 30,
        "prompt": "[Chorus]\nKeep the music playing on"
      }
    }
    ```
  </Tab>

  <Tab title="Udio">
    Udio uses a single `prompt` field for the style description. See the [Udio model page](/models/udio) for full options including `lyrics`, `tags`, `lyrics_type`, and `seed`.

    <ParamField body="input.prompt" type="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.
    </ParamField>

    ```json theme={null}
    {
      "model": "udio",
      "task_type": "music",
      "input": {
        "prompt": "lofi hip hop, chill, rainy night, jazz piano"
      }
    }
    ```
  </Tab>
</Tabs>

### `lyrics` — Generate lyrics

<ParamField body="input.prompt" type="string" required>
  A description of the lyrics you want (e.g., "A love song about the ocean at sunset").
</ParamField>

```json theme={null}
{
  "model": "suno",
  "task_type": "lyrics",
  "input": {
    "prompt": "A love song about the ocean at sunset"
  }
}
```

### `upload` — Upload audio

<ParamField body="input.url" type="string" required>
  A publicly accessible URL of the audio file to upload.
</ParamField>

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

### `concat` — Concatenate clips

<ParamField body="input.clip_id" type="string" required>
  The clip ID to concatenate (obtained from a previous music task output).
</ParamField>

```json theme={null}
{
  "model": "suno",
  "task_type": "concat",
  "input": {
    "clip_id": "abc123-clip-id"
  }
}
```

***

## Response

<ResponseField name="code" type="number">
  HTTP status code (`202` on success).
</ResponseField>

<ResponseField name="data" type="object">
  <ResponseField name="task_id" type="string">
    Unique identifier for the created task. Use this to poll for results.
  </ResponseField>

  <ResponseField name="type" type="string">
    The task type that was submitted.
  </ResponseField>

  <ResponseField name="status" type="string">
    Initial status, always `"pending"`.
  </ResponseField>

  <ResponseField name="credits_charged" type="number">
    Number of credits frozen for this task.
  </ResponseField>

  <ResponseField name="created_at" type="string">
    ISO 8601 timestamp of when the task was created.
  </ResponseField>
</ResponseField>

```json 202 theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  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
      }
    }'
  ```

  ```python Python theme={null}
  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}")
  ```

  ```javascript Node.js theme={null}
  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);
  ```
</CodeGroup>

## 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                                                           |