> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apistable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Your first request

> Generate music with the common task API and read the returned songs.

> 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.

```bash theme={null}
export APISTABLE_API_KEY="YOUR_API_KEY"
```

[Manage API keys](https://apistable.ai/console/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.

```bash theme={null}
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](https://docs.apistable.ai/suno-generate.md)

## 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.

```json theme={null}
{
  "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.

```bash theme={null}
curl 'https://apistable.ai/api/v1/tasks/YOUR_TASK_ID' \
  --header "Authorization: Bearer $APISTABLE_API_KEY"
```

[Task response fields](https://docs.apistable.ai/query-task.md)

## 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](https://docs.apistable.ai/suno-cover.md) [Extend a song](https://docs.apistable.ai/suno-extend.md) [Voice verification workflow](https://docs.apistable.ai/suno-voice-workflow.md)

## 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](https://docs.apistable.ai/webhooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.