aisplice

API reference

Music

Models on this endpoint (1)

suno
Try it in the Workbench
POST/v1/music/generations
GET/v1/music/tasks/{task_id}
GET/v1/music/tasks/{task_id}/content

Async music generation for song and instrumental workflows. Submit returns a task_id immediately; poll the task or accept a webhook callback, then read the finished audio from /content.

#Request parameters

  • modelstringrequired

    A music model ID from the models page, e.g. suno.

  • promptstringrequired

    Describe the song, mood, instrumentation, or lyric direction.

  • titlestringoptional

    Optional track title forwarded to model families that support it.

  • tagsstring | arrayoptional

    Optional genre or style hints such as cinematic, pop, or ambient.

  • versionstringoptional

    Model-family version switch when the provider exposes multiple generations.

  • mvstringoptional

    Provider-specific music mode selector; keep it server-side unless users need explicit control.

  • instrumentalbooleanoptional

    Generate instrumental output without vocals when the model supports it.

  • make_instrumentalbooleanoptional

    Alternative vendor flag for instrumental output; some providers use this instead of instrumental.

  • continue_clip_idstringoptional

    Continue or extend a previous clip instead of starting a fresh track.

  • continue_atnumberoptional

    Resume point in seconds for continuation flows.

  • webhook_urlstringoptional

    HTTPS URL called once the task reaches a terminal state.

  • webhook_secretstringoptional

    If set, deliveries carry X-Xiaoxiang-Signature: sha256=hex(HMAC-SHA256(body, secret)).

Start simple

For most products, prompt is enough for the first integration. title, tags, version, and continuation fields are advanced controls that should be added only when the product has a clear need.

Same async contract as other media tasks

Music follows the same submit → poll or webhook → /content pattern as image and video tasks, so one backend task runner can usually handle all three.

#Related errors

  • 404 not_foundUnknown path, unknown model name, or an expired / foreign task_id.
  • 422 unprocessable_entityThe vendor rejected parameter values the gateway forwarded (e.g. unsupported size or duration).
  • 401Invalid or missing bearer token. No error.code on this path — match the status.
  • 402 insufficient_user_quotaWallet balance cannot cover the pre-reserved estimate.
  • 429Per-key throttle. Empty body; wait for Retry-After. A 429 that does carry insufficient_user_quota is a daily spend cap instead.
  • 503 model_not_foundUnknown model, or no healthy channel serves it right now.

Full error-code table →

#Request example

# submit
curl https://www.aisplice.store/v1/music/generations \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno",
    "prompt": "a warm cinematic piano theme",
    "instrumental": true
  }'

# poll every 5s
curl https://www.aisplice.store/v1/music/tasks/$TASK_ID -H "Authorization: Bearer sk-YOUR_KEY"

# fetch the finished track
curl -L https://www.aisplice.store/v1/music/tasks/$TASK_ID/content \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -o song.mp3

#Response

response.json
// POST — submit accepted
{"task_id": "task_xxx", "status": "queued"}

// GET /v1/music/tasks/{task_id}
{
  "task_id": "task_xxx",
  "status": "in_progress",
  "progress": "42%"
}

// GET /v1/music/tasks/{task_id}/content
{
  "task_id": "task_xxx",
  "status": "completed",
  "metadata": {
    "audio_url": "https://…",
    "lyric": "…"
  }
}

Still stuck?

Send us the request ID or the error message and we will look into it.

PreviousVideosNext3D models