Suno

​

Endpoints

​

Authentication

Authorization: Bearer YOUR_API_KEY

​

Request Body

{
  "request_type": "async",
  "callback_url": "https://...",
  "provider": "auto",
  "input": {
    "mode": "V4_5PLUS",
    "prompt": "...",
    "customMode": true,
    "instrumental": false,
    "style": "...",
    "title": "...",
    "vocalGender": "f"
  }
}

​

Parameters

• V4 — Classic version, stable and reliable
• V4_5 — Improved version, better audio quality
• V4_5ALL — V4.5 All version
• V4_5PLUS — Enhanced version (recommended), balanced quality and speed
• V5 — Latest version, best audio quality and creativity

• customMode=true: V4 max 3000 chars, V4.5/V4.5ALL/V4.5PLUS/V5 max 5000 chars
• customMode=false: max 500 chars

• V4: max 200 chars
• V4.5/V4.5ALL/V4.5PLUS/V5: max 1000 chars

​

Example

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": "async",
    "provider": "value",
    "input": {
      "mode": "V5",
      "prompt": "upbeat pop song about summer vacation",
      "customMode": false,
      "instrumental": false
    }
  }'

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/callback",
    "provider": "official",
    "input": {
      "mode": "V4_5PLUS",
      "prompt": "Verse 1: Walking down the empty street, echoes of your laughter sweet. Chorus: I miss you more than words can say, wish you were here today.",
      "customMode": true,
      "instrumental": false,
      "style": "orchestral, emotional, film score",
      "title": "Dawn of Hope",
      "vocalGender": "f",
      "styleWeight": 0.6,
      "weirdnessConstraint": 0.2,
      "audioWeight": 0.5,
      "negativeTags": "noise, distortion"
    }
  }'

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": "async",
    "input": {
      "mode": "V4_5PLUS",
      "prompt": "cinematic orchestral track with gentle piano and strings",
      "customMode": true,
      "instrumental": true,
      "style": "orchestral, cinematic, ambient",
      "title": "Peaceful Morning",
      "styleWeight": 0.7
    }
  }'

​

Response

​

POST /api/v1/generateTask/suno

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

{
  "code": 400,
  "message": "Insufficient credits",
  "data": null
}

​

GET /api/v1/statusTask/suno

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

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[{\"image_url\":\"https://r2.apixo.ai/cover1.jpg\",\"audio_url\":\"https://r2.apixo.ai/track1.mp3\"},{\"image_url\":\"https://r2.apixo.ai/cover2.jpg\",\"audio_url\":\"https://r2.apixo.ai/track2.mp3\"}]}",
    "lyrics": "[Verse 1]\nWalking down the empty street...\n\n[Chorus]\nI miss you more than words can say...",
    "createTime": 1767965610929,
    "completeTime": 1767965652317,
    "costTime": 41388
  }
}

{
  "resultUrls": [
    {
      "image_url": "https://r2.apixo.ai/cover1.jpg",
      "audio_url": "https://r2.apixo.ai/track1.mp3"
    },
    {
      "image_url": "https://r2.apixo.ai/cover2.jpg",
      "audio_url": "https://r2.apixo.ai/track2.mp3"
    }
  ]
}

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "CONTENT_VIOLATION",
    "failMsg": "Content does not meet safety guidelines"
  }
}

​

Status Response Fields

​

Error Codes

​

Rate Limits

​

Tips

• Generation time: Average ~60-90 seconds. Submit task, wait 45 seconds, then poll every 5 seconds.
• Callback mode: Recommend using callback mode to avoid frequent polling.
• Audio expiration: Result URLs are valid for 15 days. Download promptly.
• Content moderation: Lyrics and descriptions must comply with content safety guidelines.
• Version selection:
  • V4: Classic version, stable and reliable
  • V4_5 / V4_5ALL: Improved versions, better audio quality
  • V4_5PLUS: Enhanced version (recommended), balanced quality and speed
  • V5: Latest version, best audio quality and creativity
• Custom mode vs simple mode:
  • customMode: false: Simple mode, only provide short description (max 500 chars), system auto-generates lyrics and style
  • customMode: true: Custom mode, provide full lyrics (max 5000 chars), specify style and title
• Lyrics writing tips:
  • Use standard song structure (Verse, Chorus, Bridge, etc.)
  • Leave blank lines between sections
  • Use markers like [Verse 1], [Chorus], [Bridge] to clarify structure
  • Lyrics should have rhythm and rhyme
• Style description:
  • Use music terminology (e.g., “pop”, “rock”, “jazz”, “orchestral”)
  • Combine multiple styles (e.g., “orchestral, emotional, film score”)
  • Describe mood and atmosphere (e.g., “upbeat”, “melancholic”, “energetic”)
• Vocal selection:
  • vocalGender: "m": Male voice, for lower range, powerful songs
  • vocalGender: "f": Female voice, for higher range, emotional songs
  • Not specified: System chooses based on style
• Instrumental mode:
  • instrumental: true: Generate instrumental only (no vocals)
  • Ideal for background music, soundtracks, ambiance
  • Describe instruments and atmosphere in prompt, no lyrics needed
• Weight parameter tuning:
  • styleWeight (0-1): Style intensity, higher = strictly follows specified style
  • weirdnessConstraint (0-1): Creativity level, lower = conservative, higher = innovative
  • audioWeight (0-1): Audio quality weight
  • Recommended range: 0.4-0.7
• Negative tags: Use negativeTags to avoid unwanted elements (e.g., “noise, distortion, low quality”)
• Best practices:
  • Test with simple mode first to explore styles and effects
  • Once satisfied, use custom mode for full lyrics
  • V4_5PLUS or V5 versions offer best quality
  • Clear structure and strong rhythm in lyrics yield better results
• Output format: Each generation produces 2 tracks. Each track includes an audio_url (MP3) and image_url (cover art JPG). Parse resultJson and iterate over the resultUrls array of objects — do NOT assume it is a plain string array.
• Lyrics in response: When vocals are included, the lyrics field in the status response contains the full auto-generated (or echoed) lyrics with section markers like [Verse 1], [Chorus], etc.

​

Related

• Pricing
• Error Codes