Suno V5 API Reference

Overview

Authentication

All API requests must include a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Endpoints & Workflow

1. Submit Generation Task (callback required)

POST https://api.apixo.ai/api/v1/generateTask/suno

Always send request_type: "callback" with a reachable callback_url.

2. Wait for Callback Stages

   • Suno emits up to three webhook events per task:
     1. text – lyrics/text prepared
     2. first – first track finished
     3. complete – all tracks finished
   • Parse the payload as shown in the callback sample below.

3. Fallback Polling (only if callback stalls)

   • If the first callback arrives but no additional callback within 5 minutes, call the status endpoint.
   • If you never receive complete, poll manually until success/failed.

GET https://api.apixo.ai/api/v1/statusTask/suno?taskId={taskId}

Request Parameters

Request Body Structure

{
  "request_type": "callback",
  "callback_url": "https://your-server.com/callback",
  "input": {
    "mode": "V5",
    "prompt": "Lyrics or creative brief",
    "style": "K-pop, Electronic",
    "title": "All Day With Pupu",
    "customMode": true,
    "instrumental": false
  }
}

Top-Level Parameters

Input Parameters

Core Parameters

Parameter Requirements by Mode

Non-Custom Mode (customMode: false)

Note: In non-custom mode, only prompt is required regardless of instrumental setting. Other parameters should be left empty.

Custom Mode (customMode: true)

Character Limits by Model Version

Non-custom mode: prompt limit is always 500 characters regardless of model version.

Optional Parameters

Response Format

Task Submission Response

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}

Status Query Response

Processing

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "processing",
    "createTime": 1763990437000
  }
}

Success

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[{\"image_url\":\"https://cdn2.suno.ai/image1.jpeg\",\"audio_url\":\"https://cdn1.suno.ai/track1.mp3\"},{\"image_url\":\"https://cdn2.suno.ai/image2.jpeg\",\"audio_url\":\"https://cdn1.suno.ai/track2.mp3\"}]}",
    "createTime": 1763990437000,
    "costTime": 75000
  }
}

Failed

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "CONTENT_VIOLATION",
    "failMsg": "Content does not meet safety guidelines",
    "createTime": 1763990437000,
    "completeTime": 1763990500000
  }
}

Response Fields

Callback Response

Success Callback

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[{\"image_url\":\"https://cdn2.suno.ai/image_a.jpeg\",\"audio_url\":\"https://cdn1.suno.ai/track_a.mp3\"},{\"image_url\":\"https://cdn2.suno.ai/image_b.jpeg\",\"audio_url\":\"https://cdn1.suno.ai/track_b.mp3\"}]}",
    "createTime": 1763982056689,
    "completeTime": 1763982132051,
    "costTime": 75362
  }
}

Failure Callback

{
  "code": 400,
  "message": "failed",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "CONTENT_VIOLATION",
    "failMsg": "Content does not meet safety guidelines",
    "createTime": 1763982056689,
    "completeTime": 1763982070000,
    "costTime": 13311
  }
}

Quick Start

1. Submit Generation Task

curl -X POST https://api.apixo.ai/api/v1/generateTask/suno \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "callback",
    "callback_url": "https://your-server.com/api/suno-callback",
    "input": {
      "mode": "V5",
      "prompt": "[Intro] Chill but groovy...",
      "style": "K-pop, Electronic, Lo-fi",
      "title": "All Day With Pupu",
      "customMode": true,
      "instrumental": false,
      "negativeTags": "Acoustic, Soft, Slow",
      "styleWeight": 0.9,
      "weirdnessConstraint": 0.35,
      "audioWeight": 0.7
    }
  }'

Response:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}

2. Check Task Status (Optional Polling)

curl -X GET "https://api.apixo.ai/api/v1/statusTask/suno?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (Success):

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[{\"image_url\":\"https://cdn2.suno.ai/image.jpeg\",\"audio_url\":\"https://cdn1.suno.ai/track.mp3\"}]}"
  }
}

3. Handle Callback Payload

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "complete",
    "resultJson": "{\"resultUrls\":[{\"image_url\":\"https://cdn2.suno.ai/image_a.jpeg\",\"audio_url\":\"https://cdn1.suno.ai/track_a.mp3\"},{\"image_url\":\"https://cdn2.suno.ai/image_b.jpeg\",\"audio_url\":\"https://cdn1.suno.ai/track_b.mp3\"}]}",
    "createTime": 1763982056689,
    "completeTime": 1763982132051
  }
}

Best Practices

Request Mode Selection

Performance Tips

• Generation usually completes in 2-3 minutes; avoid polling before 90 seconds, and polling interval of 10s is recommended.
• Expect three callback stages; some jobs may skip text/first and jump to complete
• Generated assets remain available for 14 days—download promptly
• Retry network errors with exponential backoff; honor rate limits

Parameter Guidance

• New users: Start with customMode: false for simpler usage—only prompt is needed
• Custom mode with vocals: When customMode: true and instrumental: false, provide full lyrics in prompt; Suno will sing them verbatim
• Custom mode instrumental: When customMode: true and instrumental: true, only style and title are needed
• Character limits: Respect model-specific limits—V4 has stricter limits (3000/200) vs V5 (5000/1000)
• Style control: Use negativeTags to exclude unwanted genres and styleWeight (0–1) to tighten adherence
• Vocal gender: vocalGender is best-effort only; combine with lyrical cues for stronger control
• Persona: Use personaId in custom mode to apply a consistent persona style across generations

Reliability & Compliance

• Ensure callback endpoints accept JSON POST bodies and respond quickly with 200
• Validate lyrics for policy compliance to avoid CONTENT_VIOLATION
• Log task IDs and callback payloads for audit and troubleshooting
• Monitor storage budgets; each job returns two MP3 + cover images