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

# Suno V6 通用约定与任务查询

> Suno V6 的版本选择、自定义模型、异步任务生命周期、源音轨引用和结果结构

> [!NOTE]
>
> 所有 Suno 生成、编辑和工具接口都采用异步任务：提交操作后取得 `task_id`，再通过本页接口查询结果。

## 认证

**Authorization** `string` *required*

使用 Bearer Token 认证：`Authorization: Bearer <你的 API Key>`。

访问 [API Key 管理页面](https://apimart.ai/keys) 获取 API Key。

## V6 版本与模型选择

公共模型只支持以下版本：

* `v6`
* `v6-wild`
* `v6-mini`

主生成接口必须提供 `version`，或提供创建模型任务返回的 `custom_model_id`。支持版本的编辑操作省略 `version` 时默认使用 `v6`。公共 `version` 与 `custom_model_id` 不能同时发送。

> [!WARNING]
>
> `custom: true` 表示自定义歌词模式，`custom_model_id` 表示使用已训练的自定义模型，两者不是同一个概念。使用自定义歌词模式不会自动切换到自定义模型价格档。

### 通用 V6 生成选项

仅在具体端点列出时发送以下字段：

| 字段 | 说明 |
| - | - |
| `variety` | 风格变化程度：`off` / `normal` / `high` / `extra` / `max` |
| `max_mode` | Max 模式，默认 `false`；支持时按普通售价的 2 倍计费 |
| `audio_format` | 输出格式：`mp3` / `m4a` / `wav` |
| `duration` / `duration_s` | 目标生成时长，10–360 秒整数，仅指定生成操作支持 |

不支持某字段的操作应完全省略该字段；不要向所有操作统一发送 `max_mode: false`。`variety` 与 Max 模式相互独立，选择 `variety: "max"` 不会自动开启 Max 计费。

### 文本与权重限制

| 内容 | 字段 | 限制 |
| - | - | - |
| 灵感描述 | `prompt`（主生成）/ `gpt_description`（操作接口） | 不超过 3000 个字符 |
| 歌词 | `prompt`（自定义模式） | 不超过 5000 个字符 |
| 风格 | `style`（主生成）/ `tags`（操作接口） | 不超过 1000 个字符 |
| 标题 | `title` | 不超过 80 个字符 |
| 权重 | `style_weight` / `weirdness` / `audio_weight` | 0–1；数值 `0` 有效 |

操作接口的新请求使用 `weirdness`；`weirdness_constraint` 是兼容别名。主生成仍使用 `weirdness_constraint`。文本长度按 Unicode 字符数计算。

## 引用源音轨

基于已有作品的操作使用：

* `task_id`：产出源音轨的 APIMart 任务 ID。
* `audio_index`：源任务查询响应的 `data.result.music[]` 中的原始位置，从 1 开始，默认 `1`。

返回多少首就按实际数组展示，不要把结果数量固定为 2。即使页面调整了展示顺序，后续操作仍须使用音轨在原始结果中的索引。

> [!WARNING]
>
> 新请求统一使用 `task_id + audio_index` 引用源音轨，不能用 `audio_id`、`music_id` 或 `audio_url` 替代。无法解析源任务或索引越界时会返回 `400`。

## 提交响应

```json theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01M24YMN4EV04M84R5QYM77R1E"
    }
  ]
}
```

从 `data[0].task_id` 读取任务 ID。`submitted` 只表示任务已受理，不表示已有最终音频或其它产物。

## 查询任务

`GET /v1/music/tasks/{task_id}`

可附加 `?language=zh` 获取适用的失败信息翻译。该参数不会改变歌曲或歌词语言。

**task\_id** `string` *required*

提交接口返回的任务 ID。

建议首次等待约 3 秒，之后每 5–10 秒查询一次，直到 `data.status` 为 `completed` 或 `failed`。页面刷新后可继续使用同一个任务 ID 查询；不要因网络超时自动重发收费的 POST 请求。

## 查询响应

**code** `integer`

响应状态码。

**data** `object`

任务信息。

**属性**

**id** `string`

本平台任务 ID。

**status** `string`

`pending` / `processing` / `completed` / `failed` / `unknown`。

**progress** `number`

任务进度，通常为 0–100。是否完成应以 `status` 为准。

**created** `number`

创建时间，Unix 秒。

**estimated\_time** `number`

预计耗时（秒），仅供参考，并非倒计时承诺。

**cost** `number`

任务金额（美元）。

**credits\_cost** `number`

任务消耗的积分值，请直接使用接口返回值展示。

**result** `object`

完成后的结果，结构随操作不同。

**error** `object`

失败信息，常见字段为 `message` / `type` / `code` / `param`。

```json completed theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01M24YMN4EV04M84R5QYM77R1E",
    "status": "completed",
    "progress": 100,
    "created": 1789041600,
    "cost": 0.12,
    "credits_cost": 1.2,
    "result": {
      "music": [
        {
          "audio_id": "example-track-id",
          "status": "complete",
          "title": "沿着灯光",
          "lyrics": "[Verse]\n晚风吹过熟悉街道",
          "tags": "pop, acoustic",
          "display_tags": "Pop, Acoustic",
          "negative_tags": "harsh vocals",
          "style_weight": 0.7,
          "weirdness_constraint": 0,
          "audio_weight": 0.4,
          "duration": 119.8,
          "audio_url": "https://example.com/result.mp3",
          "image_url": "https://example.com/cover.jpg",
          "image_large_url": "https://example.com/cover-large.jpg"
        }
      ]
    }
  }
}
```

```json failed theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01M24YMN4EV04M84R5QYM77R1E",
    "status": "failed",
    "progress": 0,
    "cost": 0,
    "credits_cost": 0,
    "error": {
      "message": "任务失败原因",
      "type": "task_failed",
      "code": "task_failed",
      "param": ""
    }
  }
}
```

## 结果处理

* 音乐类结果通常位于 `data.result.music[]`，但下载、歌词、MIDI、Persona 和自定义模型等操作有各自的结果结构。
* `duration` 是实际时长，允许小数；输入目标时长不保证与成品完全相同。
* 权重返回值 `0` 是有效值，不能因为 JavaScript falsy 判断而隐藏。
* `audio_url` 不保证使用 `.mp3` 后缀，请按接口返回的实际 URL 播放或下载。
* `status="unknown"` 时保留任务 ID 并允许手动刷新，不要自动创建新任务。

`AbortController` 只能停止浏览器请求和轮询，不会取消服务器任务。当前接口没有取消已提交 Suno 任务的端点。


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