Aibra API Documentation

Creates a queued music generation task and returns a taskId immediately.

Request

{
  "customMode": true,
  "instrumental": false,
  "model": "v6",
  "prompt": "Song lyrics",
  "style": "rock, male vocal",
  "title": "My Song",
  "callBackUrl": "https://example.com/api/aibra/callback"
}

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "song-1779890000000-a1b2c3d4"
  }
}

• Use customMode for full control over lyrics, style, title, and model.
• Choose 6 (v6), 6-wild (v6-wild), or 6-mini (v6-mini). The default is v6; older model labels and internal IDs automatically use v6.
• For custom voices, pass personaModel: "voice_persona" and the voiceId returned by the voice flow.

Creates a queued continuation of an existing Suno clip. Use the new taskId for polling or receive the final callback.

Parameter Reference

Request

{
  "audioId": "SOURCE_CLIP_ID",
  "taskId": "SOURCE_TASK_ID",
  "model": "V6",
  "lyrics": "[Verse] A new road opens with the morning light",
  "continueAt": 60,
  "variety": 1,
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65,
  "callBackUrl": "https://example.com/extend-callback"
}

Response

{"code":200,"msg":"success","data":{"taskId":"extend-..."}}

• Poll /api/v1/generate/record-info?taskId=...; successful results contain verified MP3 URLs under response.sunoData. type is EXTEND; parentMusicId is the source audioId.
• Final callbacks use data.callbackType: complete/error, data.task_id and data.data. No intermediate text/first callbacks are sent.
• The result is a continuation. Original audio is not automatically concatenated; /api/concat provides the whole-song operation separately.
• Invalid parameters and known source mismatches return HTTP 400 before generation. Queue overflow returns HTTP 429 with Retry-After.
• Known source ownership is preserved. External clips without recorded ownership require exactly one managed account. New extension submissions consume credits.
• Snake_case aliases for IDs and controls, callbackUrl/callback_url, and tags for style are accepted. Canonical fields take precedence.

Downloads a public MP3, uploads and initializes it in Suno, then creates a queued custom-mode cover.

Request

{
  "uploadUrl": "https://example.com/reference.mp3",
  "customMode": true,
  "instrumental": false,
  "model": "V5_5",
  "prompt": "[Verse]\nCover lyrics",
  "style": "Russian pop-rock, female vocal",
  "title": "My Cover",
  "negativeTags": "",
  "callBackUrl": "https://example.com/api/aibra/callback"
}

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "upload-cover-1779890000000-a1b2c3d4"
  }
}

• Only customMode: true is supported; customMode: false is rejected with HTTP 422.
• uploadUrl must be a public HTTP(S) MP3 URL. Redirects are checked and private network addresses are blocked.
• The default download limit is 100 MB. Suno still enforces account and model-specific source-duration limits.
• Poll the standard record-info endpoint or use callBackUrl for the final callback.

Polls a queued generation, extension, upload-cover, or replace-section task until it reaches a terminal status.

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "song-1779890000000-a1b2c3d4",
    "status": "SUCCESS",
    "response": {
      "sunoData": []
    }
  }
}

• Terminal statuses include SUCCESS, CREATE_TASK_FAILED, GENERATE_AUDIO_FAILED, and CALLBACK_EXCEPTION.
• The response includes snake_case media URLs plus camelCase aliases for existing integrations.

Restores playable audio links for every track of an existing completed generation task. Returns a recovery task ID immediately and processes the tracks asynchronously without generating new music.

Request

{
  "sunoTaskId": "song-1779890000000-a1b2c3d4",
  "callBackUrl": "https://example.com/api/aibra/recovery-callback"
}

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "recovery-12345678-1234-1234-1234-123456789abc"
  }
}

• sunoTaskId is the original generation task ID from this service, not an audio ID or a recovery task ID. Tasks from other providers cannot be resolved without their original clip mappings.
• callBackUrl is required and must be an HTTP(S) URL. The completion POST uses exactly the response shape shown in Get Recovery Audio Details, with task_id at the top level.
• Use the returned data.task_id to poll /api/v1/suno/recovery/record-info?task_id=... every two seconds.
• The source task must exist and be completed: an unknown source returns HTTP 404, an unfinished source returns HTTP 409, and invalid parameters return HTTP 400.
• Successful recovery also updates the original generate/record-info response. Replace old links stored by your application with the recovered audio_url values.
• source_audio_url is deprecated for long-term storage. Recovered links also expire; download and store the audio file for permanent retention, or create another recovery task when needed.

Returns recovery status and one result per original track. The completion callback uses this same JSON envelope.

Response

{
  "code": 200,
  "msg": "success",
  "task_id": "recovery-12345678-1234-1234-1234-123456789abc",
  "data": [
    {
      "id": "original-audio-id",
      "audio_url": "https://example.com/recovered-song.mp3",
      "title": "My Song",
      "status": "success",
      "error": ""
    }
  ]
}

• While processing, the JSON code is 201 and data is null; the HTTP response remains 200. Continue polling every two seconds.
• JSON code 200 means at least one track recovered. Code 500 means every track failed. Code 404 means the recovery task ID was not found.
• Track order matches the original task. Check every track: failed entries have status: failed, an empty audio_url, and an error; partial success still returns code 200.
• Errors include no_audio_id_mappings, feed_failed, clip_error, clip_not_complete, and mango_transfer_failed. Temporary service failures use neutral text.
• Callbacks have a 15-second timeout and up to three attempts. Deduplicate callbacks by task_id. If delivery fails, the result remains available through polling.
• This deployment returns verified MP3 files. Treat audio_url as the supplied URL instead of constructing a URL from the audio ID.

Returns synchronized lyric timing and waveform data for a generated clip.

Request

{
  "taskId": "song-1779890000000-a1b2c3d4",
  "audioId": "clip-id"
}

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "alignedWords": [
      {
        "word": "[Verse]\nWaggin'",
        "success": true,
        "startS": 1.36,
        "endS": 1.79,
        "palign": 0
      }
    ],
    "waveformData": [0, 1, 0.5, 0.75],
    "hootCer": 0.3803191489361702,
    "isStreamed": false
  }
}

• Use a completed generation task id and one of its sunoData clip ids.
• The adapter reuses the Suno account recorded on the source task for clip access.
• Instrumental tracks can return an empty alignedWords array.

Creates a queued task that replaces a selected section of an existing generated clip.

Request

{
  "taskId": "song-1779890000000-a1b2c3d4",
  "audioId": "clip-id",
  "prompt": "Replacement lyrics or section prompt",
  "tags": "rock, male vocal",
  "title": "My Song",
  "fullLyrics": "Full updated lyrics",
  "infillStartS": 10.5,
  "infillEndS": 20.75,
  "callBackUrl": "https://example.com/api/aibra/callback"
}

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "replace-1779890000000-a1b2c3d4"
  }
}

• The replacement window must be between 6 and 60 seconds.
• Poll the same record-info endpoint used for music generation.

Creates a reusable style persona from an existing generated clip.

Request

{
  "taskId": "song-1779890000000-a1b2c3d4",
  "audioId": "clip-id",
  "name": "Electronic Pop Singer",
  "description": "Modern electronic pop voice",
  "vocalStart": 0,
  "vocalEnd": 30,
  "style": "Electronic Pop"
}

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "personaId": "persona-id",
    "name": "Electronic Pop Singer"
  }
}

• Use the returned personaId in the music generation endpoint.
• Persona creation is recorded in the operator statistics view.

Starts the custom voice validation flow from a source voice recording.

Request

{
  "voiceUrl": "https://example.com/source-voice.mp3",
  "vocalStart": 0,
  "vocalEnd": 30,
  "language": "en",
  "callBackUrl": "https://example.com/api/aibra/callback"
}

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "voice-validate-1779890000000-a1b2c3d4"
  }
}

• The task finishes with validateInfo containing the phrase to record.
• Use validate-info to poll or receive the same information by callback.

Returns the validation phrase task state and phrase details.

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "voice-validate-1779890000000-a1b2c3d4",
    "status": "wait_validating",
    "validateInfo": {
      "phrase": "..."
    }
  }
}

• Use the phrase from validateInfo to create the verification recording.
• Regenerated phrases are also read through this endpoint.

Requests a new validation phrase for an existing validation task.

Request

{
  "taskId": "voice-validate-1779890000000-a1b2c3d4",
  "callBackUrl": "https://example.com/api/aibra/callback"
}

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "voice-validate-1779890000000-d4c3b2a1"
  }
}

• The adapter accepts callBackUrl, callbackUrl, callback_url, and calBackUrl.
• Poll the new task id with validate-info.

Verifies the recorded phrase and creates a reusable custom voice.

Request

{
  "taskId": "voice-validate-1779890000000-a1b2c3d4",
  "verifyUrl": "https://example.com/verification.mp3",
  "voiceName": "Studio Voice",
  "singerSkillLevel": "professional",
  "callBackUrl": "https://example.com/api/aibra/callback"
}

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "voice-generate-1779890000000-a1b2c3d4"
  }
}

• Use voice record-info to get the final voiceId.
• Use the voiceId as personaId with personaModel: "voice_persona" in music generation.

Returns the custom voice generation task status and final voiceId.

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "voice-generate-1779890000000-a1b2c3d4",
    "status": "SUCCESS",
    "voiceId": "voice-persona-id"
  }
}

• The endpoint can be used after callback delivery as a source of truth.
• A completed voice can be checked with the availability endpoint.

Checks whether a custom voice task or voice id is available locally.

Request

{
  "voiceId": "voice-persona-id"
}

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "available": true
  }
}

• The request can use voiceId, voice_id, taskId, or task_id.
• Availability is true after a local custom voice task completes successfully.

Separate an existing song into vocals and accompaniment, or up to 12 independent instrument stems. Receive a taskId immediately and collect results through polling or callbacks.

Parameter Reference

Request

{
  "taskId": "song-1779890000000-a1b2c3d4",
  "audioId": "clip-id",
  "callBackUrl": "https://example.com/api/aibra/callback",
  "type": "split_stem"
}

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "split-1779890000000-a1b2c3d4"
  }
}

{
  "taskId": "song-1779890000000-a1b2c3d4",
  "audioId": "clip-id",
  "callBackUrl": "https://example.com/api/aibra/callback",
  "type": "separate_vocal"
}

• Authorization: Bearer YOUR_API_KEY. Unsupported modes return HTTP 400 before a task is queued.

Get Audio Separation Details for either separation mode.

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "split-1779890000000-a1b2c3d4",
    "musicId": "clip-id",
    "callbackUrl": "https://example.com/api/aibra/callback",
    "completeTime": 1779890060000,
    "response": {
      "id": null,
      "originUrl": null,
      "originData": [
        {
          "id": "stem-0",
          "duration": 180.5,
          "audio_url": "https://media.example.com/vocal.mp3",
          "stem_type_group_name": "Vocals"
        },
        {
          "id": "stem-1",
          "duration": 180.5,
          "audio_url": "https://media.example.com/backing_vocals.mp3",
          "stem_type_group_name": "Backing Vocals"
        },
        {
          "id": "stem-2",
          "duration": 180.5,
          "audio_url": "https://media.example.com/drums.mp3",
          "stem_type_group_name": "Drums"
        },
        {
          "id": "stem-3",
          "duration": 180.5,
          "audio_url": "https://media.example.com/bass.mp3",
          "stem_type_group_name": "Bass"
        },
        {
          "id": "stem-4",
          "duration": 180.5,
          "audio_url": "https://media.example.com/guitar.mp3",
          "stem_type_group_name": "Guitar"
        },
        {
          "id": "stem-5",
          "duration": 180.5,
          "audio_url": "https://media.example.com/keyboard.mp3",
          "stem_type_group_name": "Keyboard"
        },
        {
          "id": "stem-6",
          "duration": 180.5,
          "audio_url": "https://media.example.com/percussion.mp3",
          "stem_type_group_name": "Percussion"
        },
        {
          "id": "stem-7",
          "duration": 180.5,
          "audio_url": "https://media.example.com/strings.mp3",
          "stem_type_group_name": "Strings"
        },
        {
          "id": "stem-8",
          "duration": 180.5,
          "audio_url": "https://media.example.com/synth.mp3",
          "stem_type_group_name": "Synth"
        },
        {
          "id": "stem-9",
          "duration": 180.5,
          "audio_url": "https://media.example.com/fx.mp3",
          "stem_type_group_name": "FX"
        },
        {
          "id": "stem-10",
          "duration": 180.5,
          "audio_url": "https://media.example.com/brass.mp3",
          "stem_type_group_name": "Brass"
        },
        {
          "id": "stem-11",
          "duration": 180.5,
          "audio_url": "https://media.example.com/woodwinds.mp3",
          "stem_type_group_name": "Woodwinds"
        }
      ],
      "instrumentalUrl": null,
      "vocalUrl": "https://media.example.com/vocal.mp3",
      "backingVocalsUrl": "https://media.example.com/backing_vocals.mp3",
      "drumsUrl": "https://media.example.com/drums.mp3",
      "bassUrl": "https://media.example.com/bass.mp3",
      "guitarUrl": "https://media.example.com/guitar.mp3",
      "keyboardUrl": "https://media.example.com/keyboard.mp3",
      "percussionUrl": "https://media.example.com/percussion.mp3",
      "stringsUrl": "https://media.example.com/strings.mp3",
      "synthUrl": "https://media.example.com/synth.mp3",
      "fxUrl": "https://media.example.com/fx.mp3",
      "brassUrl": "https://media.example.com/brass.mp3",
      "woodwindsUrl": "https://media.example.com/woodwinds.mp3"
    },
    "successFlag": "SUCCESS",
    "status": "SUCCESS",
    "createTime": 1779890000000,
    "errorCode": null,
    "errorMessage": null
  }
}

• The example shows canonical SunoApi.org fields; additional legacy aliases and vocal_removal_info are also returned.
• successFlag is PENDING until completion; status distinguishes PENDING from PROCESSING. response is null until SUCCESS.
• originData contains every returned track and its clip ID. Missing instrument URLs are null; split_stem does not synthesize an instrumentalUrl.
• Failures use CREATE_TASK_FAILED, GENERATE_AUDIO_FAILED or CALLBACK_EXCEPTION with errorCode and errorMessage. Retrieve record-info again to refresh expiring MP3 URLs.

Creates a queued task that converts a generated Suno clip to a lossless WAV file and returns a taskId immediately.

Request

{
  "taskId": "song-1779890000000-a1b2c3d4",
  "audioId": "clip-id",
  "callBackUrl": "https://example.com/api/aibra/wav-callback"
}

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "wav-1779890000000-a1b2c3d4"
  }
}

• The source taskId and audioId identify the exact generated clip to convert.
• The adapter reuses the source generation account, triggers Suno's on-demand WAV render for that clip, and resolves the lossless .wav URL from Suno's wav_file endpoint.
• The request accepts audioId, audio_id, musicId, music_id, clipId, and clip_id aliases.
• WAV export requires the underlying Suno account to own the clip and be allowed to export WAV files.

Returns the WAV task status and final download URL when it is ready.

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "wav-1779890000000-a1b2c3d4",
    "musicId": "clip-id",
    "musicIndex": 0,
    "successFlag": "SUCCESS",
    "response": {
      "audioWavUrl": "https://cdn1.suno.ai/clip-id.wav"
    },
    "audioWavUrl": "https://cdn1.suno.ai/clip-id.wav"
  }
}

• Terminal statuses include SUCCESS, CREATE_TASK_FAILED, GENERATE_WAV_FAILED, and CALLBACK_EXCEPTION.
• The callback payload mirrors SunoApiOrg (data.task_id, data.audioWavUrl) and adds a top-level callbackType plus wavUrl/wav_url aliases for existing mysongs handlers.

Creates a queued MP4 task for a generated Suno clip and returns a taskId immediately.

Request

{
  "taskId": "song-1779890000000-a1b2c3d4",
  "audioId": "clip-id",
  "callBackUrl": "https://example.com/api/aibra/video-callback",
  "author": "Suno Artist",
  "domainName": "music.example.com"
}

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "mp4-1779890000000-a1b2c3d4"
  }
}

• The source taskId and audioId identify the exact generated clip.
• The adapter reuses the source generation account, triggers Suno's web video render for that clip, and resolves Suno's MP4 video_url.
• The request accepts audioId, audio_id, musicId, music_id, clipId, and clip_id aliases.

Returns the MP4 task status and final video URL when it is ready.

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "mp4-1779890000000-a1b2c3d4",
    "musicId": "clip-id",
    "musicIndex": 0,
    "successFlag": "SUCCESS",
    "response": {
      "videoUrl": "https://...",
      "video_url": "https://..."
    }
  }
}

• Terminal statuses include SUCCESS, CREATE_TASK_FAILED, GENERATE_MP4_FAILED, and CALLBACK_EXCEPTION.
• Callbacks include top-level callbackType for existing mysongs handlers plus SunoApiOrg task_id/video_url fields.

Returns the current account credit and usage limit information from the Suno account behind this deployment.

Response

{
  "credits_left": 100,
  "period": "monthly"
}

• This deployment exposes the limit check through the local compatibility service.
• The exact fields are passed through from the upstream Suno account response.