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

# Crun Suno API Quickstart Guide

> Crun Suno API supports Suno's latest V5 model, enabling music generation in simple or custom modes, sound effects generation, song covers, and audio extension.

## Welcome to the Crun Suno APIs

Powered by advanced AI models, Crun Suno API offers comprehensive AI music generation and audio processing services.
Whether you need to generate music, create sound effects, extend audio, or perform vocal separation, our API can meet
all your creative needs.

## Suno AI Music Models

Supports multiple music models, including the latest Suno V5 model.

<CardGroup cols={2}>
  <Card title="V3.5" icon="bolt"> Fast Creative Output, quick idea generation. </Card>
  <Card title="V4" icon="balance-scale"> Balanced Generation Core, stable overall output.</Card>
  <Card title="V4.5" icon="stream"> Better Structure Flow, improved song flow.</Card>
  <Card title="V4.5all" icon="shapes"> Multi-Style Support, handles diverse genres.</Card>
  <Card title="V4.5plus" icon="microphone-alt"> Enhanced Vocal Control, more stable vocals.</Card>
  <Card title="V5" icon="music"> Studio-Level Quality, cleaner mix, pro sound.</Card>
  <Card title="V5.5" icon="sliders-h"> Custom Models Tailored to Your Unique Taste.</Card>
</CardGroup>

## Music Generation APIs

Providing comprehensive AI music creation and audio processing API services.

<CardGroup cols={2}>
  <Card title="Generate Music" icon="music" href="/suno-api/generate-music"> Create songs from text prompts with diverse styles. </Card>
  <Card title="Extend Music" icon="forward" href="/suno-api/extend-music"> Continue and expand existing music seamlessly. </Card>
  <Card title="Extend Upload" icon="upload" href="/suno-api/extend-music-upload"> Upload audio to extend and refine compositions. </Card>
  <Card title="Music Cover" icon="retweet" href="/suno-api/cover-music"> Recreate songs in new styles or voices. </Card>
  <Card title="Music Video" icon="video"> Generate visuals synced to your music. </Card>
  <Card title="Vocal Separation" icon="headphones"> Isolate vocals and instrument tracks cleanly. </Card>
  <Card title="Sounds Generate" icon="waveform-lines" href="/suno-api/sounds-generate"> Create sound effects, ambience, and loopable audio from text prompts. </Card>
</CardGroup>

## Getting Started

<Steps>
  <Step title="Choose Your Music APIs">
    Select the music api that best fits your use case from the categories above.
  </Step>

  <Step title="Get API Key">
    Visit the [API Key Management Page](https://crun.ai/user-api-key) to obtain your API credentials.
  </Step>

  <Step title="Integrate">
    Follow the music api specific documentation to integrate the API into your application.
  </Step>

  <Step title="Start Creating">
    Begin generating content using your chosen music api through simple API calls.
  </Step>
</Steps>

## Best Practices

### Authentication

All API requests need to include the API key in the request header.

```bash theme={null} theme={null}
X-API-KEY: YOUR_API_KEY
```

<Warning>
  Keep your API key secure. Never expose it in client-side code or public repositories.
</Warning>

### Create Task

All Suno api task creation requests follow a unified outer structure. Only the `input` field varies by model.

<Warning>
  Success is only achieved when both the HTTP status code and the business status code are 200.
</Warning>

<CodeGroup>
  ```curl cURL theme={null} theme={null}
    curl -X POST "https://api.crun.ai/api/v1/client/job/CreateTask" \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: YOUR_API_KEY" \
    -d '{
      "model": "suno/music-generate",
      "callback_url": "https://your.domain/api/v1/callback/task",
      "input": {
      "mode": "simple",
      "model": "v5",
      "instrumental": false,
      "prompt": "A modern Western R&B song with soulful female vocals, emotional and smooth tone."
  }
    }'

  ```

  ```python Python theme={null} theme={null}
  import requests

  API_KEY = "YOUR_API_KEY"
  CREATE_TASK_URL = "https://api.crun.ai/api/v1/client/job/CreateTask"

  payload = {
      "model": "suno/music-generate",
      "callback_url": "https://your.domain/api/v1/callback/task", # Use Callback Notifications
      # "callback_url": "",
      "input": {
         "mode": "simple",
         "model": "v5",
         "instrumental": False,
         "prompt": "A modern Western R&B song with soulful female vocals, emotional and smooth tone."
      }
  }
  headers = {
      "X-API-KEY": API_KEY,
      "Content-Type": "application/json"
  }
  try:
      response = requests.post(CREATE_TASK_URL, json=payload, headers=headers)
      resp_json = response.json()
      # Success requires both HTTP status code and business code to be 200
      if response.status_code == 200 and resp_json.get("code") == 200:
          # success logic
          pass
      else:
          # business error handling
          pass

  except Exception as e:
      print(f"exception occurred while creating a task: {str(e)}", )   
  ```

  ```javascript Node.js theme={null} theme={null}
  import axios from "axios";

  const API_KEY = "YOUR_API_KEY";
  const CREATE_TASK_URL = "https://api.crun.ai/api/v1/client/job/CreateTask";

  async function createTask() {
      const payload = {
          model: "suno/music-generate",
          callback_url: "https://your.domain/callback/task", // Use Callback Notifications
          // callback_url: "",
          input: {
               "mode": "simple",
               "model": "v5",
               "instrumental": false,
               "prompt": "A modern Western R&B song with soulful female vocals, emotional and smooth tone."
          }
      };

      try {
          const response = await axios.post(CREATE_TASK_URL, payload, {
              headers: {
                  "X-API-KEY": API_KEY,
                  "Content-Type": "application/json"
              }
          });

          const respJson = response.data;

          // Success requires both HTTP status code and business code to be 200
          if (response.status === 200 && respJson.code === 200) {
              // success logic
          } else {
              // business error handling
          }
      } catch (error) {
          console.error(
              "exception occurred while creating a task:",
              error.response?.data || error.message
          );
      }
  }

  createTask();

  ```
</CodeGroup>

#### Response Example

<CodeGroup>
  ```json 200 theme={null} theme={null}
  {
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "xxxx-xxxx"
  }
  }
  ```

  ```json 4xx theme={null} theme={null}
  {
  "code": 422,
  "message": "Missing Params or Type Error"
  }
  ```

  ```json 5xx theme={null} theme={null}
  {
  "code": 500,
  "message": "Internal Service Error"
  }
  ```
</CodeGroup>

### Polling Task Status

<Tip>
  Polling interval is recommended to be between 15 and 30 seconds. For production environments, we recommend webhook callbacks.
</Tip>

<CodeGroup>
  ```curl cURL theme={null} theme={null}
  curl -X GET "https://api.crun.ai/api/v1/client/job/TaskInfo?task_id=xxxx-xxxx" \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null} theme={null}
  import time
  import requests

  API_KEY = "YOUR_API_KEY"
  GET_TASK_STATUS_URL = "https://api.crun.ai/api/v1/client/job/TaskInfo"

  poll_interval = 15

  headers = {
  "X-API-KEY": API_KEY,
  "Content-Type": "application/json"
  }

  params = {
  "task_id": "xxxx-xxxx",
  }

  while True:
  response = requests.get(GET_TASK_STATUS_URL, headers=headers, params=params)
  resp_json = response.json()

      task_status = resp_json["data"]["status"]
      print(f"Task status: {task_status}")

      if task_status == "success":
          # Business success logic
          break
      elif task_status == "failed":
          # Business failure logic
          break
      else:
          # Task status is pending or running
          time.sleep(poll_interval)

  ```

  ```javascript Node.js theme={null} theme={null}
  import axios from "axios";

  const API_KEY = "YOUR_API_KEY";
  const GET_TASK_STATUS_URL = "https://api.crun.ai/api/v1/client/job/TaskInfo";

  const poll_interval = 15;

  const headers = {
    "X-API-KEY": API_KEY,
    "Content-Type": "application/json"
  };

  const params = {
    task_id: "xxxx-xxxx",
  };

  async function pollTaskStatus() {
    while (true) {
      const response = await axios.get(GET_TASK_STATUS_URL, {
        headers,
        params
      });

      const resp_json = response.data;

      const task_status = resp_json.data.status;
      console.log(`Task status: ${task_status}`);

      if (task_status === "success") {
        // Business success logic
        break;
      } else if (task_status === "failed") {
        // Business failure logic
        break;
      } else {
        // Task status is pending or running
        await new Promise((resolve) => setTimeout(resolve, poll_interval * 1000));
      }
    }
  }

  pollTaskStatus();
  ```
</CodeGroup>

#### Response Example

<CodeGroup>
  ```json task processing theme={null} theme={null}
  {
  "code": 200,
  "message": "success",
  "data": {
   "task_id": "suno_task_12345678",
   "provider": "Suno",
   "model_version": "sunov5",
    "status": "running",
    "param":  {
            "model": "suno/music-generate",
            "callback_url": "https://your.domain/api/v1/callback/task",
            "input": {
                "mode": "simple",
                "model": "v5",
                "instrumental": false,
                "prompt": "A modern Western R&B song with soulful female vocals, emotional and smooth tone."
            }
    },
    "create_at": 1773969449,
    "result": null,
    "duration_s": null,
    "complete_at": null
  }
  }
  ```

  ```json task success theme={null} theme={null}
  {
    "code": 200,
    "message": "success",
    "data": {
        "task_id": "suno_task_12345678",
        "provider": "Suno",
        "model_version": "sunov5",
        "status": "success",
        "param": {
            "model": "suno/music-generate",
            "callback_url": "https://your.domain/api/v1/callback/task",
            "input": {
                "mode": "simple",
                "model": "v5",
                "instrumental": false,
                "prompt": "A modern Western R&B song with soulful female vocals, emotional and smooth tone."
            }
        },
        "create_at": 1773969449,
        "result": {
            "code": 200,
            "message": "generation success",
            "media_urls": [
                "..."
            ],
            "suno_data": [
                {
                    "suno_id": "86c7b0a2-08e9-469e-8b90-1c80dbfdcdb6",
                    "title": "music title",
                    "prompt": "[Verse 1]\nHalf a glass on the table\nLipstick stain where you left off\nScreen ...",
                    "tags": "country, Slow-rolling modern R&B ballad with soulful female vocals over soft piano ...",
                    "suno_audio_url": "https://cdn1.suno.ai/86c7b0a2-08e9-469e-8b90-1c80dbfdcdb6.mp3",
                    "suno_image_url": "https://cdn2.suno.ai/image_86c7b0a2-08e9-469e-8b90-1c80dbfdcdb6.jpeg",
                    "suno_image_large_url": "https://cdn2.suno.ai/image_large_86c7b0a2-08e9-469e-8b90-1c80dbfdcdb6.jpeg",
                    "suno_model_name": "chirp-crow",
                    "duration": 211.68,
                    "created_at": 1773969602219
                },
                {
                    "suno_id": "d9b3b01d-fd57-4800-9524-d70d1a815bfd",
                    "title": "After Midnight Calls",
                    "prompt": "[Verse 1]\nHalf a glass on the table\nLipstick stain where you left off\nScreen ...",
                    "tags": "country, Slow-rolling modern R&B ballad with soulful female vocals over soft piano ...",
                    "suno_audio_url": "https://cdn1.suno.ai/d9b3b01d-fd57-4800-9524-d70d1a815bfd.mp3",
                    "suno_image_url": "https://cdn2.suno.ai/image_d9b3b01d-fd57-4800-9524-d70d1a815bfd.jpeg",
                    "suno_image_large_url": "https://cdn2.suno.ai/image_large_d9b3b01d-fd57-4800-9524-d70d1a815bfd.jpeg",
                    "suno_model_name": "chirp-crow",
                    "duration": 233.84,
                    "created_at": 1773969602219
                }
            ]
        },
        "duration_s": 153,
        "complete_at": 1773969602,
        "source": "api"
    }
  }
  ```

  ```json task failed theme={null} theme={null}
    {
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "suno_task_12345678",
    "provider": "Suno",
    "model_version": "sunov5",
    "status": "failed",
    "param": {
      "model": "suno/music-generate",
      "callback_url": "https://your.domain/api/v1/callback/task",
       "input": {
          "mode": "simple",
          "model": "v5",
          "instrumental": false,
          "prompt": "A modern Western R&B song with soulful female vocals, emotional and smooth tone."
       }
    }, 
    "create_at": 1773969449,
    "result": {
      "cdoe": 501,
      "message": "error message"
    },
    "duration_s": 153, 
    "complete_at": 1773969602
  }
  }
  ```
</CodeGroup>

<Tip>
  1. The task status is determined by the `status` field in the response `data` object.
  2. When `status` is `success`, retrieve the generated media URLs from `data.result.media_urls`.
  3. `data.result.suno_data` each element is a Suno music object containing information about the track.
  4. When `status` is `failed`, check the error code and message in `data.result` for details.
</Tip>

### Callback Notifications

Although polling is supported, webhook callbacks are strongly recommended for production systems., When providing
`callback_url` in the task creation request, ensure the following:

* The endpoint is publicly accessible over HTTPS.
* It responds quickly (recommended \< 3 seconds) to avoid retries.
* It returns an HTTP 200 status code upon successful receipt.
* It is idempotent. Callback notifications may be delivered more than once.

Callback payloads use the same structure as the task status query API, allowing a single unified parsing logic.

<Tip>
  When the task status changes, we will notify you of the result via a POST request.
  The payload structure is consistent with the `data` object returned by the task status query.
  For production environments, we strongly recommend using callback notifications to retrieve task results.
</Tip>

## Credits and Pricing

Different music api consume different amounts of credits based on their computational requirements.

Visit the [pricing](https://crun.ai/pricing) page to view detailed pricing for each of our musci api.

Check your remaining credits:

<CodeGroup>
  ```curl cURL theme={null} theme={null}
  curl -X POST "https://api.crun.ai/api/v1/client/account/balance" \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null} theme={null}
  import requests

  API_KEY = "YOUR_API_KEY"
  GET_BALANCE_URL = "https://api.crun.ai/api/v1/client/account/balance"

  headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}
  response = requests.post(GET_BALANCE_URL, headers=headers)

  print(response.json())

  ```

  ```javascript Node.js theme={null} theme={null}
  import axios from "axios";

  const API_KEY = "YOUR_API_KEY";
  const GET_BALANCE_URL = "https://api.crun.ai/api/v1/client/account/balance";

  const headers = {
    "X-API-KEY": API_KEY,
    "Content-Type": "application/json"
  };

  axios
    .post(GET_BALANCE_URL, null, { headers })
    .then((response) => {
      console.log(response.data);
    })
    .catch((error) => {
      console.error(error.response?.data || error.message);
    });
  ```
</CodeGroup>

## Support

Need help choosing the right model or integrating our APIs?

* Email: [support@crun.ai](mailto:support@crun.ai)
* Documentation: Browse model-specific guides in the navigation