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

# 发起第一条请求

> 通过统一任务 API 生成音乐并读取歌曲结果。

> 能力按服务端配置逐项启用。未启用操作返回 503 且不创建任务；音乐积分扣除当前未启用。

## 当前可用范围

本页说明 Suno 任务契约。是否可调用取决于部署配置：提交前查询 GET /api/v1/models?modality=music，并检查模型详情的 live\_available。文档更新不代表能力已经启用；未启用操作返回 HTTP 503，不创建任务或扣除积分。

## 1. 创建 API Key

* 在控制台 → API Keys 创建密钥，仅在服务端保存。

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

[管理 API Key](https://apistable.com/console/keys)

## 2. 提交音乐任务

顶层 model 使用 suno\_generate，input.model 选择 Suno 版本。下面的自定义模式示例提供歌词和风格。一次提交是一个执行项，通常返回两首歌曲；不传 output\_count，也不需要为两首歌曲提交两次。

```bash theme={null}
curl --request POST 'https://apistable.com/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"
  }
}'
```

[音乐生成完整参数](https://docs.apistable.com/zh/suno-generate.md)

## 3. 保存任务 ID

受理成功返回 HTTP 200 和 data.task\_id，受理不等于生成完成。保存这个 APIstable ID，后续查询同一任务。如果提交超时且无法确认是否受理，不要自动重新提交。

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "YOUR_TASK_ID"
  }
}
```

## 4. 查询直到任务结束

将 YOUR\_TASK\_ID 替换为受理时返回的任务 ID。data.status 为 processing 时，间隔一段时间继续查询；succeeded 或 failed 时停止。失败原因查看 data.message；成功前 result 为 null。

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

[任务查询响应字段](https://docs.apistable.com/zh/query-task.md)

## 5. 读取并保存歌曲

* HTTP 响应只解析一次。response.data.result 已经是对象，不要再次 JSON.parse；只有任务 input 字段仍为 JSON 字符串。
* 歌曲类任务从 response.data.result.data.data 读取歌曲数组。每首包含 id、audio\_url、title、lyrics 等元数据；可选封面和流媒体地址可能为 null。
* 歌曲 id 可作为翻唱、续写等操作的 audio\_id。所有 ID 均为 APIstable 内部 ID，由服务端映射供应商 ID。翻唱、续写使用已有 audio\_id，不接受外部 URL，也不需要源 task\_id。
* 生成文件保留 14 天，临时上传保留 24 小时，日志保留 30 天。请在过期前下载产物。音乐积分扣除当前未启用，charged\_credits 为 0。

[歌曲翻唱](https://docs.apistable.com/zh/suno-cover.md)
[歌曲续写](https://docs.apistable.com/zh/suno-extend.md)
[Voice 验证流程](https://docs.apistable.com/zh/suno-voice-workflow.md)

## 可选：接收回调

创建任务时可传公网 HTTPS callback\_url，并配置账户 Webhook 密钥。歌曲成功回调直接发送 SongResult；任务查询将同一对象放在 data.result 内。其他终态回调使用任务外层结构。接收回调时必须验证签名。

[回调签名与投递](https://docs.apistable.com/zh/webhooks.md)


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