LogoAI Music API
Sign In
APIUpload & Cover (7/10)

POST /v2/upload-cover/generate

Upload your own audio file and generate an AI cover version with a new style, lyrics, and vocal settings — while retaining the original melody. Supports both custom mode (full control over lyrics, style, title) and non-custom mode (simple prompt-based generation). Audio file must not exceed 8 minutes in length.

POSThttps://aimusicapi.org/api/v2/upload-cover/generate

Tips

Two Generation Modes:

  • Non-Custom Mode (Recommended for beginners): Set custom_mode to false. Only upload_url and prompt are required. Lyrics will be auto-generated based on the prompt (max 500 chars).
  • Custom Mode: Set custom_mode to true. You must provide upload_url, prompt (used as exact lyrics), style, and title. If make_instrumental is true, prompt can be omitted.

Image to Music (Non-Custom Mode only): Pass up to 5 publicly accessible image URLs in image_urls to steer the cover with the mood of the pictures. Adds 1 credit per request; silently ignored in Custom Mode.

Character Limits (same for every model): non-custom prompt 500, custom prompt 5000, style 1000, title 100. Longer values are truncated instead of failing.

Models & Credits: chirp-v6 = 12, chirp-v6-mini = 10, chirp-v6-wild = 12. Legacy identifiers stay valid at their historical price: chirp-v5 / chirp-v5-5 (12) are served by chirp-v6; chirp-v4-0 (8), chirp-v4-5 / chirp-v4-5-plus / chirp-v4-5-all (10) are served by chirp-v6-mini. model_name in results reports the model actually used.

Developer Notes:

  • The uploaded audio must not exceed 8 minutes.
  • Use the Status API to poll for task completion (every 5–10 seconds).
  • You may also configure a callback_url to receive results via webhook.
  • Requests rejected during validation return 422 (fix the parameters) or 500 (temporary, retry later) with data.refunded; tasks that fail after being accepted are marked FAILED and refunded automatically.

Request Headers

AuthorizationRequired

Bearer token for authentication

Content-TypeRequired

application/json

Request Body

Request body supports two modes: Non-Custom Mode (simple) or Custom Mode (full control)

Common Parameters
ParameterTypeRequiredDescriptionExample
upload_urlstringYesURL of the audio file to cover. Must be a publicly accessible URL. The audio must not exceed 8 minutes.https://storage.example.com/my-song.mp3
modelstringYesModel to use. Current options: 'chirp-v6' (12 credits), 'chirp-v6-mini' (10 credits), 'chirp-v6-wild' (12 credits). Legacy identifiers 'chirp-v4-0' (8), 'chirp-v4-5' / 'chirp-v4-5-plus' / 'chirp-v4-5-all' (10), 'chirp-v5' / 'chirp-v5-5' (12) remain accepted at their historical price and are served by chirp-v6 (chirp-v5 / chirp-v5-5) or chirp-v6-mini (all others). Unknown values return 422.chirp-v6-mini
custom_modebooleanNoEnable custom mode for full control over lyrics, style, and title. Default: false. When false, only prompt and upload_url are needed.false
image_urlsstring[]NoImage to Music. Up to 5 publicly accessible image URLs (JPEG, JPG, PNG or WEBP, max 10MB each) that steer the mood of the cover; prompt becomes optional when images are provided. Adds 1 credit per request. Non-custom mode only; silently ignored in custom mode.["https://cdn.example.com/sunset-beach.jpg"]
make_instrumentalbooleanNoGenerate instrumental music without vocals. When true in custom mode, prompt is not required.false
promptstringNoIn non-custom mode: a text description of desired output (max 500 chars, lyrics auto-generated). In custom mode: exact lyrics to be sung (max 5000 chars, longer input is truncated). Required unless make_instrumental is true or image_urls is provided.A calm and relaxing piano track with soft melodies
stylestringNoMusic style/genre (custom mode only). Max length: 1000 chars (longer input is truncated). Leave empty in non-custom mode.pop, upbeat, electronic
titlestringNoSong title (custom mode only). Max length: 100 chars (longer input is truncated). Leave empty in non-custom mode.Summer Cover
tagsstringNoNegative tags — music styles or traits to exclude from the generated audio. Custom mode only.Heavy Metal, Upbeat Drums
genderstringNoVocal gender preference. Use 'male' or 'female'. Only effective in custom mode. Note: can only increase the probability, not guarantee.female
style_weightnumberNoStrength of adherence to style. Range 0–1, up to 2 decimals.0.65
weirdness_constraintnumberNoControls creative deviation. Range 0–1, up to 2 decimals.0.65
audio_weightnumberNoBalance weight for audio features. Range 0–1, up to 2 decimals.0.65
callback_urlstringNoURL to receive webhook notifications when the task completes. Your callback endpoint should accept POST requests with JSON payload.https://api.example.com/webhook/upload-cover

Responses

{
  "code": 200,
  "message": "success",
  "workId": "upcov1a2b3c4d5e6f7890abcdef",
  "data": {
    "task_id": "upcov1a2b3c4d5e6f7890abcdef"
  }
}
{
  "code": 422,
  "message": "upload_url is required. Please provide a valid URL to your audio file (max 8 minutes)."
}
{
  "code": 422,
  "message": "Request rejected: upload_url must point to a publicly accessible audio file. Your credits have been refunded.",
  "data": {
    "task_id": "upcov1a2b3c4d5e6f7890abcdef",
    "refunded": true
  },
  "workId": "upcov1a2b3c4d5e6f7890abcdef"
}
{
  "code": 400,
  "message": "No body provided"
}
{
  "code": 401,
  "message": "No API key provided in Authorization header"
}
{
  "code": 402,
  "message": "Insufficient credits. Required: 10, Available: 3"
}
{
  "code": 500,
  "message": "The cover request could not be processed right now. Your credits have been refunded. Please retry later.",
  "data": {
    "task_id": "upcov1a2b3c4d5e6f7890abcdef",
    "refunded": true
  },
  "workId": "upcov1a2b3c4d5e6f7890abcdef"
}

Code Examples

curl -X POST "https://aimusicapi.org/api/v2/upload-cover/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v6-mini",
    "upload_url": "https://storage.example.com/my-song.mp3",
    "custom_mode": false,
    "make_instrumental": false,
    "prompt": "A calm and relaxing piano cover with soft melodies"
  }'
curl -X POST "https://aimusicapi.org/api/v2/upload-cover/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v6-mini",
    "upload_url": "https://storage.example.com/my-song.mp3",
    "custom_mode": true,
    "make_instrumental": false,
    "prompt": "[Verse]\nWalking down the street, feeling so free\n[Chorus]\nSummer dreams are calling me",
    "style": "pop, upbeat, electronic, 120 bpm",
    "title": "Summer Cover",
    "gender": "female",
    "style_weight": 0.65,
    "weirdness_constraint": 0.65,
    "audio_weight": 0.65
  }'
const response = await fetch('https://aimusicapi.org/api/v2/upload-cover/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'chirp-v6-mini',
    upload_url: 'https://storage.example.com/my-song.mp3',
    custom_mode: false,
    make_instrumental: false,
    prompt: 'A calm and relaxing piano cover with soft melodies'
  })
});

const data = await response.json();
console.log(data);
// { code: 200, message: "success", workId: "upcov...", data: { task_id: "upcov..." } }

// Then poll for status:
const statusRes = await fetch(
  'https://aimusicapi.org/api/v2/upload-cover/status?task_id=' + data.data.task_id,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const status = await statusRes.json();
console.log(status);

GET /v2/upload-cover/status?task_id=xxx

Check the status and results of an Upload & Cover task. Poll this endpoint every 5–10 seconds until the task completes or fails. Credits are automatically refunded if the task fails.

GEThttps://aimusicapi.org/api/v2/upload-cover/status?task_id=xxx

Tips

Status Types:

  • IN_PROGRESS: Task is still being processed. Keep polling.
  • SUCCESS: Task completed successfully. response_data contains the generated audio URLs.
  • FAILED: Task failed (e.g., content moderation violation). Credits are refunded automatically.
  • ERROR: An error occurred during processing.

Failure Detection: Check fail_message and error_message fields in the response data for error details like "Does Not Meet Guidelines".

Poll this endpoint every 5–10 seconds until generation completes or fails.

Request Parameters

task_idstringRequired

The unique task ID returned from the generate endpoint.

Responses

{
  "code": 200,
  "message": "success",
  "data": {
    "type": "IN_PROGRESS",
    "request_body": {
      "model": "chirp-v6-mini",
      "upload_url": "https://storage.example.com/my-song.mp3",
      "custom_mode": false,
      "prompt": "A calm and relaxing piano cover"
    },
    "response_data": null,
    "created_at": "2026-02-07T12:00:00.000Z"
  }
}
{
  "code": 200,
  "message": "success",
  "data": {
    "type": "SUCCESS",
    "request_body": {
      "model": "chirp-v6-mini",
      "upload_url": "https://storage.example.com/my-song.mp3",
      "custom_mode": false,
      "prompt": "A calm and relaxing piano cover"
    },
    "response_data": [
      {
        "id": "e231xxxx-xxxx-xxxx-xxxx-xxxx8cadc7dc",
        "audio_url": "https://cdn1.suno.ai/xxxx.mp3",
        "image_url": "https://cdn2.suno.ai/image_xxxx.jpeg",
        "image_large_url": "https://cdn2.suno.ai/image_xxxx.jpeg",
        "created_at": "2026-02-07T12:00:00.000Z",
        "status": "complete",
        "title": "Summer Cover",
        "prompt": "[Verse] Walking down the street, feeling so free",
        "tags": "pop, upbeat",
        "duration": 198.44,
        "model_name": "chirp-v6-mini",
        "extra_message": "synced_from_api",
        "fail_message": "",
        "error_message": ""
      },
      {
        "id": "bd15xxxx-xxxx-xxxx-xxxx-xxxxxxxx1873",
        "audio_url": "https://cdn1.suno.ai/yyyy.mp3",
        "image_url": "https://cdn2.suno.ai/image_yyyy.jpeg",
        "image_large_url": "https://cdn2.suno.ai/image_yyyy.jpeg",
        "created_at": "2026-02-07T12:00:00.000Z",
        "status": "complete",
        "title": "Summer Cover",
        "prompt": "[Verse] Walking down the street, feeling so free",
        "tags": "pop, upbeat",
        "duration": 228.28,
        "model_name": "chirp-v6-mini",
        "extra_message": "synced_from_api",
        "fail_message": "",
        "error_message": ""
      }
    ],
    "created_at": "2026-02-07T12:00:00.000Z"
  }
}
{
  "code": 200,
  "message": "success",
  "data": {
    "type": "FAILED",
    "request_body": {
      "model": "chirp-v6-mini",
      "upload_url": "https://storage.example.com/my-song.mp3",
      "custom_mode": false,
      "prompt": "..."
    },
    "response_data": [
      {
        "status": "FAILED",
        "fail_message": "Does Not Meet Guidelines",
        "error_message": "Does Not Meet Guidelines"
      },
      {
        "status": "FAILED",
        "fail_message": "Does Not Meet Guidelines",
        "error_message": "Does Not Meet Guidelines"
      }
    ],
    "created_at": "2026-02-07T12:00:00.000Z"
  }
}
{
  "code": 404,
  "message": "Task not found",
  "data": null
}
{
  "code": 500,
  "message": "Internal Server Error",
  "data": null
}

Code Examples

curl -X GET "https://aimusicapi.org/api/v2/upload-cover/status?task_id=upcov1a2b3c4d5e6f7890abcdef" \
  -H "Authorization: Bearer YOUR_API_KEY"
// Poll until completed
async function pollStatus(taskId) {
  while (true) {
    const res = await fetch(
      'https://aimusicapi.org/api/v2/upload-cover/status?task_id=' + taskId,
      { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
    );
    const result = await res.json();

    if (result.data?.type === 'SUCCESS') {
      console.log('Audio URLs:', result.data.response_data.map(d => d.audio_url));
      return result;
    }
    if (result.data?.type === 'FAILED' || result.data?.type === 'ERROR') {
      console.error('Task failed:', result.data.response_data);
      return result;
    }

    // Still in progress, wait 5 seconds
    await new Promise(r => setTimeout(r, 5000));
  }
}