---
title: "Run a follow-up action on a completed Suno job"
method: POST
path: "/v2/music/suno/action"
tags: ["Music"]
---

# Run a follow-up action on a completed Suno job

`POST /v2/music/suno/action`

## Request

- Base URL: `https://api.apiframe.ai`
- URL: `https://api.apiframe.ai/v2/music/suno/action`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Runs a follow-up action on a completed `suno` job, referenced by its job ID. Every action selects one of the parent's tracks with `index` (1–2) or `trackId` (from the parent's `result.tracks[].id`). `extend` continues the track from `continueAt` (seconds; defaults to the end of the track and must be less than its duration). `cover` re-generates the track in a new style while keeping its core melody (`audio_weight` 0–1 controls how closely it follows the source). `add_vocals` layers AI-generated vocals onto the track — `prompt` (the lyrics) is required; intended for instrumental parents. `stems` splits the track into separate vocals and instrumental audio files. Optional `prompt` (lyrics in custom mode, a description otherwise), `title`, `style`, and `negative_tags` override the inherited values. Extend, cover, and add_vocals results are fresh pairs of Suno tracks and can be acted on again; stems results are 2 plain audio files (`vocals` + `instrumental`) that accept no further actions. Returns 409 when the action is not available for the parent job.

## Headers

- `Idempotency-Key` string

## Request body

- union: Discriminated by `action`. All actions select a track from a completed Suno job with `index` (1–2) or `trackId`. `extend` continues the track from `continueAt` (defaults to the end of the track); `cover` re-generates it in a new style while keeping its melody; `add_vocals` layers AI vocals (required `prompt` = lyrics) onto it; `stems` splits it into vocals + instrumental files.
  - object
    - `action` 'extend', required
    - `continueAt` number
    - `prompt` string
    - `title` string
    - `style` string
    - `negative_tags` string
    - `parentJobId` string, uuid, required
    - `index` union
      - 1
      - 2
    - `trackId` string
    - `webhookUrl` string, uri
    - `webhookEvents` string[]
  - object
    - `action` 'cover', required
    - `prompt` string
    - `title` string
    - `style` string
    - `negative_tags` string
    - `audio_weight` number
    - `parentJobId` string, uuid, required
    - `index` union
      - 1
      - 2
    - `trackId` string
    - `webhookUrl` string, uri
    - `webhookEvents` string[]
  - object
    - `action` 'add_vocals', required
    - `prompt` string, required
    - `title` string
    - `style` string
    - `negative_tags` string
    - `parentJobId` string, uuid, required
    - `index` union
      - 1
      - 2
    - `trackId` string
    - `webhookUrl` string, uri
    - `webhookEvents` string[]
  - object
    - `action` 'stems', required
    - `parentJobId` string, uuid, required
    - `index` union
      - 1
      - 2
    - `trackId` string
    - `webhookUrl` string, uri
    - `webhookEvents` string[]

## Response `202`

Job accepted and queued. Track via `GET /v2/jobs/{id}` or webhook.

- JobAccepted: Returned by every successful job submission.
  - `jobId` string, uuid, required
  - `status` 'QUEUED' | 'PROCESSING' | 'COMPLETED' | 'FAILED', required: Status at the moment the job record was persisted. Almost always `QUEUED`; idempotent replays may return the original status.

## Other responses

- `400`: Request body failed validation.
- `401`: Authentication failed (missing / invalid API key).
- `402`: Team has insufficient credits to run this model.
- `403`: Authenticated but the API key is inactive or lacks permission.
- `429`: Rate limit exceeded. Retry after the `Retry-After` seconds.
- `503`: Service temporarily unavailable (queue / DB outage). Retry with backoff.

---

[API](https://skmtc.dev/apiframe/apis/apiframe-api.md) · [All operations](https://skmtc.dev/apiframe/apis/apiframe-api/llms.txt) · [OpenAPI document](https://skmtc.dev/apiframe/apis/apiframe-api/revisions/ba1a4c26c86a?raw)