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

# 批量上传 Session

> 在同一 Suno 账号上批量上传多个音频

若多次调用单独的 [上传音频](/zh/api-reference/suno/upload)，每次可能落在**不同 Suno 账号**，后续无法用于需要同账号的操作（如 [Inspiration](/zh/api-reference/suno/inspiration)、[创建 Persona](/zh/api-reference/suno/persona) 等）。

**批量上传 Session** 在 prepare 阶段锁定一个账号，该 session 内所有 item 均上传到**同一账号**。

## 流程概览

```
Step 1: POST /suno/v2/audio/upload/session
        → sessionId（同步选定账号）

Step 2: POST /suno/v2/audio/upload/session/item  （×N，可并发）
        → 每个文件一个 taskId（异步）

Step 3: GET /suno/v2/status?taskId={sessionId}
        → 聚合的 audioIds[]
```

| 步骤 | 接口                                        | 类型     | 说明                          |
| -- | ----------------------------------------- | ------ | --------------------------- |
| 1  | `POST /suno/v2/audio/upload/session`      | 同步     | 选账号，返回 `sessionId`          |
| 2  | `POST /suno/v2/audio/upload/session/item` | 异步 × N | 在绑定账号上传单个文件                 |
| 3  | `GET /suno/v2/status?taskId={sessionId}`  | 查询     | `data.audioIds` 为全部 clip ID |

<Info>
  现有 `POST /suno/v2/upload` **不受影响**。仅在需要**多个 clip 同账号**时使用 Session 流程。
</Info>

***

## Step 1 — 创建 Session

[准备上传 Session](/zh/api-reference/suno/uploadSessionPrepare) — 无请求体。

**响应：**

```json theme={null}
{
  "sessionId": "f259907e-32dd-468d-95f9-e3c0baf4f01c"
}
```

* 同步返回
* 内部随机选一个可用上传账号并绑定到 session
* Session 任务状态为 `success`，`result.audioIds` 初始为 `[]`

***

## Step 2 — 上传音频（可并发）

[上传 Session Item](/zh/api-reference/suno/uploadSessionItem) — 每个文件调用一次。

```json theme={null}
{
  "sessionId": "f259907e-32dd-468d-95f9-e3c0baf4f01c",
  "audioUrl": "https://example.com/audio.mp3"
}
```

**响应：**

```json theme={null}
{
  "taskId": "833c3d28-7948-42b8-9d4c-4c145bddfbf5"
}
```

* 异步 — 用 item 的 `taskId` 轮询 [查询任务状态](/zh/api-reference/suno/task)
* 同一 `sessionId` 可并发提交多个 item，**共用同一账号**
* 每个 item 成功后，clip ID 自动追加到 session 的 `audioIds`
* 单次上传积分与普通上传相同

***

## Step 3 — 查询进度与聚合结果

### 单个 item 进度

```
GET /suno/v2/status?taskId={itemTaskId}
```

**成功示例：**

```json theme={null}
{
  "taskId": "833c3d28-...",
  "status": "success",
  "data": {
    "id": "e9fe2c0e-189d-4a0a-9f4d-354b1c47b99c",
    "status": "complete",
    "audio_url": "https://cdn1.suno.ai/....mp3",
    "image_url": "https://cdn2.suno.ai/....jpeg",
    "has_vocal": true,
    "display_tags": "indie pop, electronic pop, male vocals"
  }
}
```

### Session 聚合（全部 clip ID）

```
GET /suno/v2/status?taskId={sessionId}
```

```json theme={null}
{
  "taskId": "f259907e-...",
  "status": "success",
  "data": {
    "audioIds": [
      "e9fe2c0e-189d-4a0a-9f4d-354b1c47b99c",
      "4595e4da-af12-4c24-a013-9cfd11db7d50"
    ]
  }
}
```

`audioIds` 随每个 item 完成实时追加；进行中的 item 不会出现在列表中。

***

## 同账号保证机制

```
prepare  →  随机选账号 → session.accountId = 500046

item 创建  →  task.accountId = session.accountId（创建时写死）

item 执行  →  pickAccount(ById, 500046) + 行锁，绝不切换账号
```

***

## 与 Custom Model 上传对比

|                      | Custom Model 上传          | 批量上传 Session（本功能）            |
| -------------------- | ------------------------ | ---------------------------- |
| 账号                   | 专用定制模型账号                 | 随机可用上传账号                     |
| 后续                   | `customModelCreate` 训练   | 无，`audioIds` 可直接使用           |
| 场景                   | 训练 `chirp-custom:<uuid>` | Persona、Inspiration 等通用同账号场景 |
| prepare 后 session 状态 | `READY`（等待 create）       | `success`（prepare 即终态）       |

***

## 完整示例

<CodeGroup>
  ```bash Step 1 — 创建 session theme={null}
  curl -X POST https://api.mountsea.ai/suno/v2/audio/upload/session \
    -H "Authorization: Bearer your-api-key"
  ```

  ```bash Step 2 — 上传（每个文件重复） theme={null}
  curl -X POST https://api.mountsea.ai/suno/v2/audio/upload/session/item \
    -H "Authorization: Bearer your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "sessionId": "f259907e-32dd-468d-95f9-e3c0baf4f01c",
      "audioUrl": "https://example.com/a.mp3"
    }'
  ```

  ```bash Step 3 — Session 聚合 theme={null}
  curl "https://api.mountsea.ai/suno/v2/status?taskId=f259907e-32dd-468d-95f9-e3c0baf4f01c" \
    -H "Authorization: Bearer your-api-key"
  ```
</CodeGroup>

<Tip>
  将返回的 `audioIds` 用于 [Inspiration](/zh/api-reference/suno/inspiration) 的 `clip_ids`，或其它需要同账号的生成/角色流程。
</Tip>