Skip to main content

Unofficial Python library for Suno AI API: make a song with Suno using v3 🥳

Project description

Suno AI API

GitHub PyPI

Suno AI API is

  • An unofficial Python library for Suno AI API

Suno AI API supports to

  • Create a Python client for Suno AI
  • Utilize Chirp v3 model to make a song by default
  • Continue from a song
  • Make a song using CLI
  • Deploy a REST API available at http://http://127.0.0.1/:8000
  • Deploy with Docker
  • Deploy on Vercel

Installation

pip install suno-api

or

git clone git@github.com:imyizhang/suno-api.git
cd suno-api
poetry install --only main

Quickstart

Sign in to Suno AI at https://app.suno.ai/, and get your cookie

You can find your cookie from the browser's Developer Tools -> Network tab

Screenshot

Create a client for Suno AI with your cookie

import suno

client = suno.Suno(cookie="your-cookie-here")

Create your clips

clips = client.songs.generate(
    "your-song-description-here", 
    instrumental=False,
)

or start with custom mode

clips = client.songs.generate(
    "your-lyrics-here", 
    cutomized=True,
    tags="your-music-style-here",
    instrumental=False,
)

Review your newly created clip

clip = client.songs.get("your-clip-id-here")

Review all your created clips in the library

clips = client.songs.list()

Check your remaining credits

credits = client.get_credits()

Download a clip on Suno AI

suno.download("your-clip-id-here")

Documentation

Python Library

suno.Song

suno.Song(*args, **kwargs)

An object representing a song.

Properties:

id (str): Unique ID for the song.

video_url (str): Video URL for the song.

audio_url (str): Audio URL for the song.

image_url (str | None): Image URL for the song.

image_large_url (str | None): Large image URL for the song.

major_model_version (str): Major model version used to create the song.

model_name (str): Model name used to create the song.

metadata (dict): Metadata of the song.

is_liked (bool): The song is liked or not.

user_id (str): Unique ID for a user who created the song.

is_trashed (bool): The song is trashed or not.

reaction (dict | None): Reaction to the song.

created (str): When the song was created.

status (str): Status for the song.

title (str): Title for the song.

play_count (int): Play count for the song.

upvote_count (int): Upvote count for song.

is_public (bool): The song is public or not.

suno.Suno

suno.Suno(cookie: str)

A object representing a client for Suno AI.

Parameters:

  • cookie (str): Cookie stored for the cookie-based authentication.

Properties:

headers (dict): Request headers.

songs.generate(prompt: str, custom: bool, tags: str, instrumental: bool)

Create songs.

Each song generation consumes 5 credits, thus a total of 10 credits is necessary for each successful call.

Parameters:

  • prompt (str): Prompt used to create the song, song, description, lyrics, or style of music.
  • custom (bool, optional): Whether to create the song in custom mode. Defaults to False.
  • tags (str, optional): Tags indicating musical style of the song to be created. Defaults to "".
  • instrumental (bool, optional): Whether to create the song without lyrics. Defaults to False.

Returns:

(List[suno.Song]): A list of suno.Song objects representing the created songs.

get_songs()

List all songs (equivalent to songs.list()).

Returns:

(List[suno.Song]): A list of suno.Song objects representing the songs in the library of the logged-in account.

get_song(id: str)

Get a song by its ID (equivalent to songs.get(id: str)).

Parameters:

  • id (str): ID of the song.

Returns:

(suno.Song): A suno.Song object representing the song.

get_credits()

Get all credits left.

Returns:

(int): Remaining credits in the logged-in account.

suno.download

suno.download(song: str | suno.Song, root: str)

Download a song.

Parameters:

  • song (str | suno.Song): ID indicating a song, URL linked to a song or an suno.Song object.
  • root (str): Root directory to store the downloaded songs.

REST API

Set environment variable SUNO_COOKIE

Check the value of the environment variable SUNO_COOKIE on macOS
echo $SUNO_COOKIE
Add the environment variable SUNO_COOKIE permanently on macOS

Find your current shell.

echo $0

In zsh, a environment variable can be permanently added to the configuration file ~/.zshrc. In bash, the configuration file is ~/.bash_profile.

vim ~/.zshrc

In the configuration file, add the environment variable SUNO_COOKIE.

export SUNO_COOKIE="your-cookie-here"

Save the changes to the configuration file and execute it.

source ~/.zshrc

Deployment

git clone git@github.com:imyizhang/suno-api.git
cd suno-api/suno
uvicorn api:app --reload

or

git clone git@github.com:imyizhang/suno-api.git
cd suno-api
poetry run python suno/api.py

POST /v1/songs

Create songs.

Request example

cURL

curl -X POST "http://localhost:8000/v1/songs" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "Make a song about the moon"}'

Suno AI CLI

suno songs generate "Make a song about the moon"

Python

import json

import requests

data = json.dumps({
    "prompt": "Make a song about the moon",
})

response = requests.post("http://localhost:8000/v1/songs", data=data)
response.json()

GET v1/songs

List all songs.

Request example

cURL

curl -X GET "http://localhost:8000/v1/songs" \
     -H "Accept: application/json"

Suno AI CLI

suno songs list

Python

import requests

response = requests.get('http://localhost:8000/v1/songs')
response.json()

GET v1/song/{id}

Get a song by its ID.

Request example

cURL

curl -X GET "http://localhost:8000/v1/songs/{id}" \
     -H "Accept: application/json"

Suno AI CLI

suno songs get ID

Python

import requests

response = requests.get('http://localhost:8000/v1/songs/{id}')
response.json()
Response Example
{
  "id":"0e42f167-17ab-4004-941b-d549b24dce76",
  "video_url":"https://cdn1.suno.ai/0e42f167-17ab-4004-941b-d549b24dce76.mp4",
  "audio_url":"https://cdn1.suno.ai/0e42f167-17ab-4004-941b-d549b24dce76.mp3",
  "image_url":"https://cdn1.suno.ai/image_75b03116-0aa2-4367-bdf6-8556dde4df9f.png",
  "image_large_url":"https://cdn1.suno.ai/image_large_75b03116-0aa2-4367-bdf6-8556dde4df9f.png",
  "major_model_version":"v3",
  "model_name":"chirp-v3",
  "metadata":{
    "tags":"Rap\nJapanese rock\nPop\nVocaloid style\nEnergetic\nUpbeat\nCatchy\nCulinary\nCooking\nRecipe-focused",
    "prompt":"[Chorus]\nIn der Weihnachtsbäckerei\nGibt es manche Leckerei\nZwischen Mehl und Milch\nMacht so mancher Knilch\nEine riesengroße Kleckerei\nIn der Weihnachtsbäckerei\nIn der Weihnachtsbäckerei\n\n[Verse 1]\nWo ist das Rezept geblieben\nVon den Plätzchen, die wir lieben?\nWer hat das Rezept verschleppt?\n\"Ich nicht\"\n\"Du vielleicht?\"\n\"Ich auch nicht\"\n\nNa, dann müssen wir es packen\nEinfach frei nach Schnauze backen\nSchmeißt den Ofen an (oh ja)\nUnd ran\n\n[Chorus]\nIn der Weihnachtsbäckerei\nGibt es manche Leckerei\nZwischen Mehl und Milch\nMacht so mancher Knilch\nEine riesengroße Kleckerei\nIn der Weihnachtsbäckerei\nIn der Weihnachtsbäckerei\n\n[Verse 2]\nBrauchen wir nicht Schokolade\nHonig, Nüsse und Succade\nUnd ein bischen Zimt?\nDas stimmt\n\nButter, Mehl und Milch verrühren\nZwischendurch einmal probieren\nUnd dann kommt das Ei (pass auf)\nVorbei\n\n[Chorus]\nIn der Weihnachtsbäckerei\nGibt es manche Leckerei\nZwischen Mehl und Milch\nMacht so mancher Knilch\nEine riesengroße Kleckerei\nIn der Weihnachtsbäckerei\nIn der Weihnachtsbäckerei\n\n[Verse 3]\nBitte mal zur Seite treten\nDenn wir brauchen Platz zum kneten\nSind die Finger rein?\nDu Schwein\n\n\nSind die Plätzchen, die wir stechen\nErstmal auf den Ofenblechen\nWarten wir gespannt\nVerbrannt\n\n[Chorus]\nIn der Weihnachtsbäckerei\nGibt es manche Leckerei\nZwischen Mehl und Milch\nMacht so mancher Knilch\nEine riesengroße Kleckerei\nIn der Weihnachtsbäckerei\nIn der Weihnachtsbäckerei\n\n[Outro]",
    "gpt_description_prompt":"None",
    "audio_prompt_id":"None",
    "history":"None",
    "concat_history":[
      {
        "id":"7b9cfa43-d231-44e8-b69a-d9c0627b016d",
        "continue_at":107.0
      },
      {
        "id":"75b03116-0aa2-4367-bdf6-8556dde4df9f",
        "continue_at":"None"
      }
    ],
    "type":"concat",
    "duration":158.83997916666667,
    "refund_credits":"None",
    "stream":"None",
    "error_type":"None",
    "error_message":"None"
  },
  "is_liked":false,
  "user_id":"cb7486d0-238e-409e-9ff9-e69db325fa84",
  "is_trashed":false,
  "reaction":"None",
  "created_at":"2024-03-24T13:46:25.916Z",
  "status":"complete",
  "title":"In der Weihnachtsbäckerei ",
  "play_count":0,
  "upvote_count":724,
  "is_public":true
}

GET v1/credits

Get all credits left.

Request example

cURL

curl -X GET "http://localhost:8000/v1/credits" \
     -H "Accept: application/json"

Suno AI CLI

suno credits display

Python

import requests

response = requests.get('http://localhost:8000/v1/credits')
response.json()
Response Example
{
  "total_credits_left": 50
}

License

Suno AI API has a BSD-3-Clause license, as found in the LICENSE file.

Contributing

Thanks for your interest in contributing to Suno AI API! Please feel free to create a pull request.

Changelog

Suno AI API 0.1.2

  • Add a function to download any song on Suno AI
  • Fix bugs for song generation

Suno AI API 0.1.1

  • Introduce suno.Song to structure suno.Suno methods' outputs
  • Support environment variable SUNO_COOKIE
  • Support CLI for Suno AI API
  • Allow to deploy REST API for Suno AI API

Suno AI API 0.1.0

  • Quickly generate a song with a description
  • Create songs with lyrics and music style in custom mode
  • Review songs using their ID
  • List all songs in the library

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

suno_api-0.1.2.tar.gz (11.9 kB view details)

Uploaded Source

Built Distribution

suno_api-0.1.2-py3-none-any.whl (10.4 kB view details)

Uploaded Python 3

File details

Details for the file suno_api-0.1.2.tar.gz.

File metadata

  • Download URL: suno_api-0.1.2.tar.gz
  • Upload date:
  • Size: 11.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.7.1 CPython/3.12.0 Darwin/21.6.0

File hashes

Hashes for suno_api-0.1.2.tar.gz
Algorithm Hash digest
SHA256 4b95752cf2afa8aa5e5c8400bbb0685b95fee52a7771a5d5db248ff163c37799
MD5 2aab2175152a40ec88c0a76bdd016a43
BLAKE2b-256 aa41dae758673cec459cdad7a2af48248ffe3244bc9c1e46ca137070269a37e4

See more details on using hashes here.

Provenance

File details

Details for the file suno_api-0.1.2-py3-none-any.whl.

File metadata

  • Download URL: suno_api-0.1.2-py3-none-any.whl
  • Upload date:
  • Size: 10.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.7.1 CPython/3.12.0 Darwin/21.6.0

File hashes

Hashes for suno_api-0.1.2-py3-none-any.whl
Algorithm Hash digest
SHA256 c5364a3daaaa0b9961b4ee84789677eb9cf193ac1c30ea8d4d078e72c67ad9af
MD5 9826a8dbdba44c6f6f98915cc10f82d7
BLAKE2b-256 b207a109c06b6205ef25983ddf1a9f84b41ef2f6506a92c19336fa84dbabb040

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page