跳转到主要内容

​
接口

MethodEndpointDescription
POST/api/v1/generateTask/suno创建生成任务
GET/api/v1/statusTask/suno查询任务状态

​
认证

所有请求需在请求头中携带 API Key： 
Authorization: Bearer YOUR_API_KEY

​
请求体

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

​
参数

​
request_type
string
默认值:"async"
async (polling) or callback (webhook)
​
callback_url
string
Callback URL, required when request_type=callback (conditional)
​
provider
string
默认值:"auto"
Routing strategy: auto, value, or official
​
input
object
必填
Model input parameters
Mode Options:
  • 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
Prompt Length Limits:
  • customMode=true: V4 max 3000 chars, V4.5/V4.5ALL/V4.5PLUS/V5 max 5000 chars
  • customMode=false: max 500 chars
Style Length Limits:
  • V4: max 200 chars
  • V4.5/V4.5ALL/V4.5PLUS/V5: max 1000 chars

​
示例

Simple Mode (Non-Custom) 
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
    }
  }'
Custom Mode (with Lyrics) 
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"
    }
  }'
Instrumental (No Vocals) 
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
    }
  }'

​
响应

​
POST /api/v1/generateTask/suno

Returns taskId on success for subsequent status queries. Success: 
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}
Error: 
{
  "code": 400,
  "message": "Insufficient credits",
  "data": null
}

​
GET /api/v1/statusTask/suno

Query task execution status and results via taskId. 
curl -X GET "https://api.apixo.ai/api/v1/statusTask/suno?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"
Success: 
{
  "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
  }
}
resultJson format for Suno — Unlike image/video models that return a plain URL array, Suno returns an array of objects containing both audio_url (MP3) and image_url (cover art JPG). Each generation typically produces 2 tracks with their respective cover images.
Parsed resultJson structure: 
{
  "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"
    }
  ]
}
Field in each itemTypeDescription
audio_urlstringMP3 audio file URL
image_urlstringCover art image URL (JPG)
Failed: 
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "CONTENT_VIOLATION",
    "failMsg": "Content does not meet safety guidelines"
  }
}

​
状态响应字段

​
taskId
string
Unique task identifier.
​
state
string
Current task state: pending, processing, success, or failed.
​
resultJson
string
JSON string containing resultUrls array. Only present on success. Parse with JSON.parse().
​
failCode
string
Error code. Only present when state is failed. See 错误码.
​
failMsg
string
Human-readable error message. Only present when state is failed.
​
createTime
integer
Task creation timestamp (Unix milliseconds).
​
completeTime
integer
Task completion timestamp (Unix milliseconds).
​
costTime
integer
Processing duration in milliseconds.

​
错误码

CodeDescription
400Invalid parameters or request error
401Invalid or missing API Key
429Rate limit exceeded
Fail CodeDescription
CONTENT_VIOLATIONContent violates safety guidelines

​
速率限制

LimitValue
Requests10000 / minute
Concurrent tasks1000
Exceeding limits returns 429 error. Wait and retry.

​
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.
Each generation produces 2 tracks with cover art. Result URLs expire after 15 days; download important outputs promptly.

​
相关