Your first request

Operations are enabled individually by server configuration. Disabled operations return 503 without a task. Music credit deduction is currently disabled.

Current availability

This guide describes the Suno task contract. Availability depends on the deployment: check GET /api/v1/models?modality=music and the model detail live_available flag before submitting. Documentation updates do not enable an operation. A disabled operation returns HTTP 503 without creating a task or charging credits.

1. Create an API key

Create a key in Console → API Keys and keep it on your server.

export APISTABLE_API_KEY="YOUR_API_KEY"

Manage API keys

2. Submit a music task

Set the top-level model to suno_generate. input.model selects the Suno version. This custom-mode example supplies its own lyrics and style. One submission creates one execution item and normally returns two songs; do not add output_count or submit twice to obtain the pair.

curl --request POST 'https://apistable.ai/api/v1/tasks/create_task' \
  --header "Authorization: Bearer $APISTABLE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "suno_generate",
  "input": {
    "model": "V6",
    "custom_mode": true,
    "instrumental": false,
    "title": "Paper boats at dawn",
    "style": "Fingerpicked guitar, gentle brushed drums",
    "lyrics": "[Verse]\nWe fold a map into a boat\nAnd let the morning carry it home"
  }
}'

All music generation parameters

3. Save the task ID

An accepted request returns HTTP 200 with data.task_id. Acceptance is not completion. Save this APIstable ID and query the existing task. If submission times out and acceptance is unknown, do not automatically submit again.

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "YOUR_TASK_ID"
  }
}

4. Query until completion

Replace YOUR_TASK_ID with the accepted task ID. While data.status is processing, keep querying with a delay between requests. Stop when it is succeeded or failed; on failure, inspect data.message. result is null before success.

curl 'https://apistable.ai/api/v1/tasks/YOUR_TASK_ID' \
  --header "Authorization: Bearer $APISTABLE_API_KEY"

Task response fields

5. Read and save the songs

Parse the HTTP response once. response.data.result is already an object; do not JSON.parse it again. Only the task input field remains a JSON string.
For song-producing operations, read response.data.result.data.data. Each entry has id, audio_url, title, lyrics and other song metadata. Optional artwork and stream URLs may be null.
Use a song id as audio_id for cover, extend and other song operations. These are APIstable IDs; the server resolves provider IDs. Cover and extend accept an existing audio_id, not an external URL or a source task_id.
Generated files are retained for 14 days, temporary uploads for 24 hours and logs for 30 days. Download outputs before expiry. Music credit deduction is currently disabled and charged_credits is 0.

Cover a song Extend a song Voice verification workflow

Optional: receive a callback

Provide a public HTTPS callback_url at task creation and configure your account webhook secret. Successful song callbacks contain the SongResult directly; task queries wrap that same object inside data.result. Other terminal callbacks use the task envelope. Verify the signature before accepting a callback. Callback signatures and delivery

Getting started with APIstable

Market

Your first request

Current availability

1. Create an API key

2. Submit a music task

3. Save the task ID

4. Query until completion

5. Read and save the songs

Optional: receive a callback

​Current availability

​1. Create an API key

​2. Submit a music task

​3. Save the task ID

​4. Query until completion

​5. Read and save the songs

​Optional: receive a callback

Current availability

1. Create an API key

2. Submit a music task

3. Save the task ID

4. Query until completion

5. Read and save the songs

Optional: receive a callback