More

Settings

API Documentation

Use your API key to generate music, extend audio, separate stems and more via the REST API.

Studio subscription required

API access and API key creation are available only to Studio subscribers. You can read these docs publicly, but you need an active Studio plan to create keys and call the API.

Compare Studio plans

Authentication

All API requests require a Bearer token. Use your API key in the Authorization header.

Authorization: Bearer sk-your-api-key-here

Base URL

https://acestep.io

API Keys Management

Create and manage your API keys at Settings → API Keys

API key creation is available only for active Studio subscribers.

https://acestep.io/settings/apikeys

Task Status Reference

V2 Studio batches use queued, completed, failed, cancelled, and expired. Submission and provider processing are internal attempt details.

The initial provider attempt plus up to three automatic retries is the maximum. A queued batch can be cancelled after 60 minutes; an incomplete batch expires after 6 hours and receives one full refund.

Status responses include recovery metadata: attempt_count, can_cancel, cancellable_at, max_attempts, next_retry_at, next_reconcile_at, terminal_reason.

{
  "code": 0,
  "msg": "success",
  "data": {
    "tasks": [{
      "task_id": "85841517381530180",
      "status": "queued",
      "progress": 0,
      "message": "Queued",
      "audio_url": null,
      "lrc": null,
      "created_at": "2026-06-05T15:54:33Z",
      "attempt_count": 1,
      "max_attempts": 4,
      "can_cancel": true,
      "cancellable_at": "2026-06-05T16:54:33Z",
      "next_retry_at": null,
      "next_reconcile_at": "2026-06-05T17:09:33Z",
      "terminal_reason": null
    }]
  }
}
queuedcompletedfailedcancelledexpired

API Endpoints

POST/api/v2/generate-audio5 / 10 credits

Generate Music from Text

Create AI-generated music from style tags and lyrics. Supports instrumental mode and studio quality.

Request Body

{
  "tags": "pop, energetic, synth, dance",
  "lyrics": "[Intro]\\n[Verse 1]\\n...",
  "seconds": 60,
  "steps": 12,
  "studio_quality": false
}

Response

// studio_quality=false: 2 normal tasks, 5 credits
{
  "code": 0,
  "data": {
    "tasks": [
      { "task_id": "83082474758221335" },
      { "task_id": "83082475022272525" }
    ],
    "credits_consumed": 5,
    "remaining_credits": 781
  }
}

// studio_quality=true: 1 studio task, 10 credits
{
  "code": 0,
  "data": {
    "tasks": [
      { "task_id": "83082478890054944" }
    ],
    "credits_consumed": 10,
    "remaining_credits": 771
  }
}
GET/api/v2/task-status/{task_id}Free credits

Query Task Status

Poll the status of any generation task. Use the task_id returned from creation endpoints.

Response

// Normal task: flat response
{
  "code": 0,
  "data": {
    "task_id": "83082474758221335",
    "status": "completed",
    "progress": 100,
    "message": "Success",
    "audio_url": "https://cdn.acestep.io/...mp3",
    "lrc": "[00:00.00][Intro]...",
    "created_at": "2026-06-05T15:54:33Z"
  }
}

// Multi-output task: each sibling carries the same fields as a normal task
{
  "code": 0,
  "data": {
    "tasks": [
      { "task_id": "xxx", "status": "completed", "progress": 100, "message": "Success", "audio_url": "https://cdn.acestep.io/...mp3", "lrc": "[00:00.00][Intro]...", "created_at": "2026-06-05T15:54:33Z" },
      { "task_id": "yyy", "status": "completed", "progress": 100, "message": "Success", "audio_url": "https://cdn.acestep.io/...mp3", "lrc": "[00:00.00][Intro]...", "created_at": "2026-06-05T15:54:33Z" }
    ]
  }
}
POST/api/v2/extend-audio5 credits

Extend Audio Duration

Extend an existing track by generating additional audio at the specified time range.

Request Body

{
  "srcTaskId": "source-task-id",
  "srcAudioUrl": "https://cdn.acestep.io/...mp3",
  "caption": "extend with guitar solo",
  "repaintingStart": 55,
  "repaintingEnd": 65
}

Response

{
  "code": 0,
  "data": {
    "task_id": "83082578055174907",
    "status": "queued",
    "credits_consumed": 5,
    "remaining_credits": 766
  }
}
POST/api/v2/replace-section5 credits

Replace Audio Section

Replace a section of existing audio with new content (3-60 seconds region).

Request Body

{
  "srcTaskId": "source-task-id",
  "srcAudioUrl": "https://cdn.acestep.io/...mp3",
  "caption": "drum solo section",
  "repaintingStart": 20,
  "repaintingEnd": 30
}

Response

{
  "code": 0,
  "data": {
    "task_id": "83082581023354167",
    "status": "queued",
    "credits_consumed": 5,
    "remaining_credits": 761
  }
}
POST/api/v2/add-stem5 credits

Add Instrument Stem

Add a new instrument track. Valid tracks: woodwinds, brass, fx, synth, strings, percussion, keyboard, guitar, bass, drums, backing_vocals, vocals.

Request Body

{
  "srcTaskId": "source-task-id",
  "srcAudioUrl": "https://cdn.acestep.io/...mp3",
  "caption": "add keyboard layer",
  "selectedTrack": "keyboard"
}

Response

{
  "code": 0,
  "data": {
    "task_id": "83082714928845380",
    "status": "queued",
    "credits_consumed": 5,
    "remaining_credits": 731
  }
}
POST/api/v2/cover-audio5 credits

Create Cover Version

Generate a cover version of existing audio with new style and lyrics.

Request Body

{
  "srcTaskId": "source-task-id",
  "srcAudioUrl": "https://cdn.acestep.io/...mp3",
  "caption": "acoustic cover version"
}

Response

{
  "code": 0,
  "data": {
    "task_id": "83082589527341345",
    "status": "queued",
    "credits_consumed": 5,
    "remaining_credits": 746
  }
}
POST/api/v2/generate-lyricsFree credits

Generate Lyrics

Generate song lyrics and style tags from a theme using AI. Free, no credits required.

Request Body

{
  "theme": "a lonely astronaut floating in deep space"
}

Response

{
  "code": 0,
  "data": {
    "tags": "cinematic, ambient, melancholic...",
    "lyrics": "[Intro]\\n(Ethereal synth pads...)..."
  }
}
POST/api/v2/tasks/{task_id}/cancelFree credits

Cancel a Queued Batch

Cancel the entire V2 Studio billing batch after it has remained queued for 60 minutes. Cancellation stops recovery, discards incomplete outputs, and refunds the full original charge exactly once, even when one output already exists.

Response

// Success: cancellation covers the whole original billing batch
{
  "code": 0,
  "data": {
    "task_id": "85841517381530180",
    "status": "cancelled",
    "credits_refunded": 10
  }
}

// 409 before cancellable_at, after completion, or after another settlement
{
  "code": 409,
  "msg": "cancellation_not_available",
  "data": null
}

// A partial result is discarded and the full original charge is refunded exactly once.

The endpoint returns 409 cancellation_not_available before the 60-minute boundary, task_already_completed after completion, or batch_already_settled after another terminal settlement.

GET/api/v2/download-audio/{task_id}Free credits

Download Audio

Download generated audio file as attachment.

Response

Binary audio stream (audio/mpeg)