Aibra API Documentation

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

Request

{
  "customMode": true,
  "instrumental": false,
  "model": "v4.5-all",
  "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.
• Supported model labels include v5.5, v5, v4.5+, v4.5, v4.5-all, and v4.
• For custom voices, pass personaModel: "voice_persona" and the voiceId returned by the voice flow.

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, 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.

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.

Creates a queued task that separates vocals and instrumental stems.

Request

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

Response

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

• The source taskId and audioId are kept for traceability.
• Completion returns direct vocalUrl and instrumentalUrl aliases.

Returns the stem separation task status and output URLs.

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "vocal-removal-1779890000000-a1b2c3d4",
    "status": "SUCCESS",
    "vocalUrl": "https://...",
    "instrumentalUrl": "https://..."
  }
}

• Use this endpoint to reconcile callback delivery failures.
• The response includes a vocal_removal_info object for clients that expect it.

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.