Suno AI

compatible

https://back.gard-api.org/api/v1/suno

Music generation, extend, stems, WAV, MIDI, video — all in one place on Gard. Every route lives under /api/v1/suno.

Models — use Custom mode and set model to one of: V4, V4_5, V4_5PLUS, V4_5ALL, V5, V5_5.

Task ids — async jobs return a taskId with a short prefix (gs_ generate, gse_ extend, gsl_ lyrics, …). Poll GET …/generate/record-info with that value (same role as upstream Suno poll — not feed / query).

API Keys Open playground Export Docs

Errors

JSON bodies use code, msg, and data. Some logical failures still return HTTP 200 with a non‑200 code inside the JSON — always read the envelope.

Typical HTTP status codes

401 — missing or invalid API key.
402 — not enough Gard credits for this call.
422 — validation error (wrong or missing fields).
500 — server-side error.

Example — invalid API key

{
  "code": 401,
  "msg": "Invalid API key",
  "data": null
}

Example — insufficient credits

{
  "code": 402,
  "msg": "Insufficient credits. Please purchase more.",
  "data": null
}

Example — validation

{
  "code": 422,
  "msg": "…",
  "data": null
}

Authentication

Create an API key in the dashboard, then send it on every request as X-API-Key: gard_….

Base URL

https://back.gard-api.org

curl https://back.gard-api.org/api/v1/suno/generate \
  -H "X-API-Key: gard_..." \
  -H "Content-Type: application/json" \
  -d '{"customMode":true,"instrumental":false,"model":"V5","prompt":"ambient piano","style":"ambient","title":"Demo"}'

Endpoints

GET: query parameters as one object (no JSON body on the wire). Multipart routes: logical fields — send as form-data, values shown as JSON for clarity.

POST

/api/v1/suno/generate

Create a new track. Custom mode: customMode: true, choose model V4–V5_5, lyrics or idea in prompt, style tags in style.

Request body

Field	Type	Required	Description
customMode	boolean	no	Must be `true` when using `model` below.
instrumental	boolean	no	true — instrumental only (no vocals).
model	string	yes	Engine version. Options: `V4 · V4_5 · V4_5PLUS · V4_5ALL · V5 · V5_5`
prompt	string	no	Lyrics text or creative brief.
style	string	no	Genres / style tags.
title	string	no	Track title.
callBackUrl	string	no	HTTPS URL for completion webhook.

Example request (JSON)

{
  "customMode": true,
  "instrumental": false,
  "model": "V5",
  "prompt": "Verse about the sea at dawn, hopeful mood",
  "style": "indie folk, acoustic guitar, soft drums",
  "title": "Dawn Tide",
  "vocalGender": "f",
  "styleWeight": 0.75,
  "weirdnessConstraint": 0.35,
  "callBackUrl": "https://your-app.com/webhooks/gard-suno"
}

Example response (JSON)

{
  "code": 200,
  "msg": "success",
  "data": { "taskId": "gs_xxxxxxxxxxxxxxxx" }
}

Polling: GET /api/v1/suno/generate/record-info?taskId=<taskId from response>. Wait until data.status is SUCCESS; finished clips live in data.response.sunoData[] (audioUrl; duplicates may appear as audio_url). Same semantics as upstream record-info, with Gard public taskId prefixes. Do not confuse with feed / query — those query clips by UUID only.

GET

/api/v1/suno/generate/record-info

Task status and clips (primary polling). Gard GET /api/v1/suno/generate/record-info — parsing and shape match upstream after proxying.

Example request (JSON)

GET /api/v1/suno/generate/record-info?taskId=gs_xxxxxxxxxxxxxxxx

Example response (JSON)

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "gs_xxxxxxxxxxxxxxxx",
    "status": "SUCCESS",
    "type": "GENERATE",
    "response": {
      "taskId": "gs_xxxxxxxxxxxxxxxx",
      "sunoData": [
        {
          "id": "clip-uuid-from-suno",
          "audioUrl": "https://…/….mp3",
          "title": "Dawn Tide",
          "tags": "indie folk",
          "duration": 198
        }
      ]
    },
    "errorCode": null,
    "errorMessage": null
  }
}

Poll until SUCCESS. MP3 URLs: audioUrl in sunoData[] (also check streamAudioUrl when needed).

POST

/api/v1/suno/generate/extend

Continue an existing clip from continueAt (seconds).

Request body

Field	Type	Required	Description
audioId	string	yes	Clip id from `record-info` / `feed`.
model	string	no	V4 … V5_5.

Example request (JSON)

{
  "audioId": "clip_from_previous_job",
  "model": "V5",
  "prompt": "extend with an outro, same energy",
  "style": "indie folk, acoustic",
  "title": "Dawn Tide (extended)",
  "continueAt": 48.0,
  "defaultParamFlag": true,
  "callBackUrl": "https://your-app.com/webhooks/gard-suno"
}

Example response (JSON)

{ "code": 200, "msg": "success", "data": { "taskId": "gse_xxxxxxxxxxxxxxxx" } }

Task id prefix: gse_.

POST

/api/v1/suno/generate/upload-cover

Cover / remake from an uploaded file or audio URL.

Request body

Field	Type	Required	Description
file OR uploadUrl	file \| string	no	Either `file` or `uploadUrl` is required.

Example request (JSON)

// JSON variant (no file):

{
  "uploadUrl": "https://your-cdn.com/reference.mp3",
  "customMode": true,
  "instrumental": false,
  "model": "V5",
  "title": "My Cover",
  "prompt": "same vibe, new arrangement",
  "tags": "synthwave, dreamy",
  "callBackUrl": "https://your-app.com/webhooks/gard-suno"
}

// Multipart: field file + the same text fields as form entries.

Example response (JSON)

{ "code": 200, "msg": "success", "data": { "taskId": "gsuc_xxxxxxxxxxxxxxxx" } }

POST

/api/v1/suno/generate/upload-extend

Upload audio and extend it.

Example request (JSON)

{
  "uploadUrl": "https://your-cdn.com/stem.wav",
  "continueAt": 0,
  "model": "V5",
  "prompt": "continue the groove",
  "title": "Extended jam",
  "tags": "funk, bass",
  "callBackUrl": "https://your-app.com/webhooks/gard-suno"
}

// Or multipart: file + the fields above as form fields.

Example response (JSON)

{ "code": 200, "msg": "success", "data": { "taskId": "gsue_xxxxxxxxxxxxxxxx" } }

POST

/api/v1/suno/generate/replace-section

Replace a segment (infill) between infillStartS and infillEndS.

Request body

Field	Type	Required	Description
taskId	string	yes	Parent task `gs_…`.
audioId	string	yes	Clip to edit.

Example request (JSON)

{
  "taskId": "gs_parent_task_id",
  "audioId": "clip_to_edit",
  "prompt": "new lyrics for this section only",
  "tags": "pop, bright",
  "title": "My Track (edit)",
  "infillStartS": 12.5,
  "infillEndS": 28.0,
  "fullLyrics": null,
  "negativeTags": "metal",
  "callBackUrl": "https://your-app.com/webhooks/gard-suno"
}

Example response (JSON)

{ "code": 200, "msg": "success", "data": { "taskId": "gsrs_xxxxxxxxxxxxxxxx" } }

POST

/api/v1/suno/generate/add-instrumental

Add instrumental bed under vocals (underpaint).

Request body

Field	Type	Required	Description
audioId	string	yes	Clip that contains vocals.

Example request (JSON)

{
  "audioId": "vocals_only_clip_id",
  "prompt": "soft piano and brush drums",
  "title": "With bed",
  "style": "lo-fi, warm",
  "model": "V5",
  "negativeTags": "distortion",
  "callBackUrl": "https://your-app.com/webhooks/gard-suno"
}

Example response (JSON)

{ "code": 200, "msg": "success", "data": { "taskId": "gsai_xxxxxxxxxxxxxxxx" } }

POST

/api/v1/suno/generate/add-vocals

Add vocals on top of an instrumental (overpaint).

Request body

Field	Type	Required	Description
audioId	string	yes	Instrumental clip.
prompt	string	yes	Vocal lyrics / brief.

Example request (JSON)

{
  "audioId": "instrumental_clip_id",
  "prompt": "Verse 1:\nLine one...\nLine two...",
  "title": "With vocals",
  "style": "pop soul",
  "model": "V5",
  "callBackUrl": "https://your-app.com/webhooks/gard-suno"
}

Example response (JSON)

{ "code": 200, "msg": "success", "data": { "taskId": "gsav_xxxxxxxxxxxxxxxx" } }

POST

/api/v1/suno/generate/generate-persona

Create a persona from a clip.

Example request (JSON)

{
  "audioId": "clip_id",
  "name": "Studio Persona A",
  "taskId": "gs_optional_parent_task",
  "description": "warm baritone ad-libs",
  "isPublic": true,
  "personaType": "vox",
  "vocalStart": 10.0,
  "vocalEnd": 45.0,
  "style": "neo-soul",
  "callBackUrl": "https://your-app.com/webhooks/gard-suno"
}

Example response (JSON)

{
  "code": 200,
  "msg": "success",
  "data": { "personaId": "gsp_xxxxxxxxxxxxxxxx", "name": "Studio Persona A", "description": "…" }
}

GET

/api/v1/suno/generate/persona-status

Persona creation status.

Example request (JSON)

(query only)

GET /api/v1/suno/generate/persona-status?personaId=gsp_xxxxxxxxxxxxxxxx

Example response (JSON)

{ "code": 200, "msg": "success", "data": { "status": "…" } }

POST

/api/v1/suno/style/generate

Boost style tags derived from free-text descriptors.

Example request (JSON)

{
  "content": "Pop, Mysterious"
}

Example response (JSON)

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "<string>",
    "param": "<string>",
    "result": "<string>",
    "successFlag": "<string>",
    "errorCode": 123,
    "errorMessage": "<string>",
    "createTime": "<string>"
  }
}

Body must include content — comma-separated tags (e.g. "Pop, Mysterious"). Gard forwards this shape upstream. The JSON data object typically mirrors the upstream task envelope (taskId, param, result, successFlag, errorCode, errorMessage, createTime).

POST

/api/v1/suno/lyrics

Generate lyrics from a prompt.

Request body

Field	Type	Required	Description
prompt	string	yes	Topic or brief.

Example request (JSON)

{
  "prompt": "Upbeat lyrics about Friday night city lights, no profanity",
  "callBackUrl": "https://your-app.com/webhooks/gard-suno"
}

Example response (JSON)

{ "code": 200, "msg": "success", "data": { "taskId": "gsl_xxxxxxxxxxxxxxxx" } }

GET

/api/v1/suno/lyrics/record-info

Lyrics generation result.

Example request (JSON)

GET /api/v1/suno/lyrics/record-info?taskId=gsl_xxxxxxxxxxxxxxxx

Example response (JSON)

{
  "code": 200,
  "msg": "success",
  "data": { "id": "lyrics_row", "text": "…", "status": "complete" }
}

POST

/api/v1/suno/generate/get-timestamped-lyrics

Line-level timestamps for a clip.

Example request (JSON)

{
  "audioId": "clip_id",
  "taskId": "gs_optional_parent_task"
}

Example response (JSON)

{
  "code": 200,
  "msg": "success",
  "data": { "lines": [{ "time": 0.0, "text": "First line" }, { "time": 3.2, "text": "Second line" }] }
}

POST

/api/v1/suno/suno/cover/generate

Album art image for a track.

Example request (JSON)

{
  "taskId": "gs_finished_generation_task",
  "callBackUrl": "https://your-app.com/webhooks/gard-suno"
}

// Or without taskId — audio URL only:
{
  "audioUrl": "https://your-cdn.com/track.mp3",
  "callBackUrl": "https://your-app.com/webhooks/gard-suno"
}

Example response (JSON)

{
  "code": 200,
  "msg": "success",
  "data": { "taskId": "gsco_xxxxxxxxxxxxxxxx", "images": ["https://…"] }
}

GET

/api/v1/suno/suno/cover/record-info

Cover generation status.

Example request (JSON)

GET /api/v1/suno/suno/cover/record-info?taskId=gsco_xxxxxxxxxxxxxxxx

Example response (JSON)

{ "code": 200, "msg": "success", "data": { "status": "complete", "images": ["https://…"] } }

POST

/api/v1/suno/wav/generate

Export WAV.

Example request (JSON)

{
  "audioId": "clip_id",
  "taskId": "gs_parent_task_optional",
  "callBackUrl": "https://your-app.com/webhooks/gard-suno"
}

Example response (JSON)

{ "code": 200, "msg": "success", "data": { "taskId": "gswv_xxxxxxxxxxxxxxxx" } }

GET

/api/v1/suno/wav/record-info

Finished WAV download info.

Example request (JSON)

GET /api/v1/suno/wav/record-info?taskId=gswv_xxxxxxxxxxxxxxxx

Example response (JSON)

{
  "code": 200,
  "msg": "success",
  "data": { "audio_wav_url": "https://…", "task_id": "gswv_xxxxxxxxxxxxxxxx" }
}

POST

/api/v1/suno/vocal-removal/generate

Stem separation / vocal isolation.

Example request (JSON)

{
  "taskId": "gs_parent_task",
  "audioId": "clip_id",
  "type": "separate_vocal",
  "callBackUrl": "https://your-app.com/webhooks/gard-suno"
}

Example response (JSON)

{ "code": 200, "msg": "success", "data": { "taskId": "gsvr_xxxxxxxxxxxxxxxx" } }

Set type in JSON: separate_vocal (default) — 2 stems (vocals + instrumental), quick vocal removal / karaoke — 4.5 credits. split_stem — up to 12 stems (vocals, backing vocals, drums, bass, guitar, keyboard, strings, brass, woodwinds, percussion, synth, FX/other) for advanced mixing — 23 credits.

POST

/api/v1/suno/generate/upload-vocal-removal

Stems from an uploaded file (multipart).

Example request (JSON)

multipart/form-data:

  file = @mix.wav
  (+ optional taskId, callBackUrl as plain form fields)

Example response (JSON)

{ "code": 200, "msg": "success", "data": { "taskId": "gsuv_xxxxxxxxxxxxxxxx" } }

Same pricing as POST /vocal-removal/generate: multipart field type — separate_vocal (default) 4.5 credits, split_stem 23 credits.

GET

/api/v1/suno/vocal-removal/record-info

Stem separation result.

Example request (JSON)

GET /api/v1/suno/vocal-removal/record-info?taskId=gsvr_xxxxxxxxxxxxxxxx

Example response (JSON)

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "gsvr_xxxxxxxxxxxxxxxx",
    "vocal_separation_info": {
      "stems": [
        { "stem_type": "vocals", "audio_url": "https://…" },
        { "stem_type": "instrumental", "audio_url": "https://…" }
      ]
    }
  }
}

POST

/api/v1/suno/midi/generate

MIDI from audio.

Example request (JSON)

{
  "audioId": "clip_id",
  "callBackUrl": "https://your-app.com/webhooks/gard-suno"
}

Example response (JSON)

{ "code": 200, "msg": "success", "data": { "taskId": "gsmi_xxxxxxxxxxxxxxxx" } }

GET

/api/v1/suno/midi/record-info

MIDI job result.

Example request (JSON)

GET /api/v1/suno/midi/record-info?taskId=gsmi_xxxxxxxxxxxxxxxx

Example response (JSON)

{
  "code": 200,
  "msg": "success",
  "data": { "taskId": "gsmi_xxxxxxxxxxxxxxxx", "state": "complete", "instruments": [] }
}

POST

/api/v1/suno/generate/sounds

Sound effects.

Example request (JSON)

{
  "prompt": "Short riser for podcast intro, 3 seconds",
  "model": "V5",
  "soundLoop": false,
  "soundTempo": 120,
  "soundKey": "C minor",
  "grabLyrics": false,
  "callBackUrl": "https://your-app.com/webhooks/gard-suno"
}

Example response (JSON)

{ "code": 200, "msg": "success", "data": { "taskId": "gssf_xxxxxxxxxxxxxxxx" } }

POST

/api/v1/suno/generate/mashup

Mashup two sources.

Example request (JSON)

{
  "audioId_1": "first_clip_id",
  "audioId_2": "second_clip_id",
  "customMode": true,
  "instrumental": false,
  "model": "V5",
  "prompt": "blend into one chorus",
  "style": "electronic, house",
  "title": "Mash 01",
  "callBackUrl": "https://your-app.com/webhooks/gard-suno"
}

// Alternative:
// "uploadUrlList": ["https://…/a.mp3", "https://…/b.mp3"]

Example response (JSON)

{ "code": 200, "msg": "success", "data": { "taskId": "gsmu_xxxxxxxxxxxxxxxx" } }

POST

/api/v1/suno/generate/mp4

Video from audio (simplified multipart flow).

Example request (JSON)

multipart/form-data:

  audioId = clip_id
  callBackUrl = https://your-app.com/webhooks/gard-suno

Example response (JSON)

{ "code": 200, "msg": "success", "data": { "taskId": "gsvi_xxxxxxxxxxxxxxxx" } }

Billing: 0 Gard credits. After POST you receive taskId in data. Poll GET /api/v1/suno/generate/record-info?taskId=<taskId> (same envelope as music generation) until status completes, or use callBackUrl webhooks.

GET

/api/v1/suno/generate/waveform

Waveform points for visualization.

Example request (JSON)

GET /api/v1/suno/generate/waveform?audioId=clip_id

Example response (JSON)

{ "code": 200, "msg": "success", "data": { "waveformData": [0.12, 0.34, …] } }

Callback (webhook)

Optional: set **`callBackUrl`** on async requests to receive a POST when the job finishes.

If you pass callBackUrl (HTTPS) in the request body, we POST a JSON payload there when the job completes. The shape uses code, msg, and data; inside data you will see fields such as callbackType (complete, error, and sometimes intermediate states for long jobs), task_id, and clip rows with URLs and metadata.

POST https://your-app.com/suno/callback
Content-Type: application/json

{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "gs_xxxxxxxx",
    "data": [
      {
        "id": "…",
        "audio_url": "https://…",
        "title": "My Song",
        "model_name": "V5",
        "tags": "pop"
      }
    ]
  }
}