API Reference

SkyStudio API Gateway — v1

Current Model

The public gateway model slug is ace-step-1.5. It is currently backed by ACE-Step 1.5 XL Turbo (internal config acestep-v15-xl-turbo).

The public API contract uses the stable slug ace-step-1.5. Internal worker config names are not part of the client contract.

Authentication

All requests require an API key passed in the Authorization header:

Authorization: Bearer sk-your-api-key

API key management is currently provisioned for internal and staged access. Manage your API keys →

Endpoints

POST/api/v1/generateSubmit a generation job

GET/api/v1/jobs/:idPoll job status

POST/api/v1/jobs/:id/cancelCancel a job and return its latest state

Async Job Model

All generation requests are asynchronous. You submit a job, receive a job ID, and poll until it completes. Results are returned via output_url.

Generation is not synchronous. Do not expect audio data in the initial response.

For compiler-assisted Simple Mode requests, poll responses may also include compiled_input so clients can inspect or persist the effective prompt and lyrics that actually reached the worker.

POST /api/v1/jobs/:id/cancel is idempotent. Local-only jobs are cancelled immediately; submitted or running jobs attempt provider cancellation and then return the latest reconciled state.

Idempotency

To safely retry requests, include an Idempotency-Key header (or idempotency_key in the request body). Use a UUID v4 per unique request.

curl -X POST https://api.skystudioai.com/api/v1/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ace-step-1.5",
    "input": {
      "prompt": "jazz piano"
    }
  }'

If the same key is reused, the API returns 409 with the existing job ID:

{
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "Duplicate idempotency key",
    "details": { "existing_job_id": "36abd4da-..." }
  }
}

Result Contract

Completed jobs return an output_url pointing to the generated file on our CDN (assets.skystudios.app). This is the primary way to retrieve results.

Public API output_url files under gateway/music/ are retained for 15 days. Poll responses include output_expires_at for those short-retention URLs.

audio_base64 is an internal fallback only. Always use output_url.

When Simple Mode compilation runs, GET /api/v1/jobs/:id may also return compiled_input with the effective prompt, lyrics, optional tempo, and compiler metadata.

{
  "id": "36abd4da-cf45-4bd0-...",
  "status": "completed",
  "output_url": "https://assets.skystudios.app/gateway/music/.../result.mp3",
  "output_expires_at": "2026-05-09T00:00:00.000Z",
  "compiled_input": {
    "prompt": "Warm cinematic piano theme with soft strings and gradual lift",
    "lyrics": "[Intro]\n[Main Theme]\n[Outro]",
    "bpm": 72,
    "vocal_language": "en",
    "compiler_used": true,
    "compiler_model": "gemini-3.1-flash-lite-preview",
    "compiler_mode": "instrumental"
  }
}

This is useful if you want to sync auto-generated lyrics into your own history view, expose a developer debug panel, or understand whether the request used compiler output or fallback behavior.

Error Codes

All errors follow the shape: { "error": { "code": "...", "message": "..." } }

HTTP	Code	Meaning
`401`	`UNAUTHORIZED`	Missing or invalid API key
`401`	`KEY_REVOKED`	API key has been revoked
`401`	`KEY_EXPIRED`	API key has expired
`402`	`INSUFFICIENT_CREDITS`	Not enough credits for this request
`404`	`NOT_FOUND`	Job or resource not found
`409`	`IDEMPOTENCY_CONFLICT`	Duplicate idempotency key
`429`	`RATE_LIMITED`	Too many requests per minute
`429`	`CONCURRENCY_LIMITED`	Too many concurrent jobs
`500`	`INTERNAL_ERROR`	Server error

429 responses include a Retry-After header (seconds).

Quick Start

1. Submit a music generation request:

curl -X POST https://api.skystudioai.com/api/v1/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ace-step-1.5",
    "input": {
      "prompt": "upbeat electronic dance music",
      "duration": 30,
      "format": "mp3"
    }
  }'

Response:

{
  "id": "36abd4da-cf45-4bd0-...",
  "status": "submitted",
  "model": "ace-step-1.5",
  "estimated_credits": 30,
  "poll_url": "/api/v1/jobs/36abd4da-cf45-4bd0-..."
}

2. Poll until completed:

curl https://api.skystudioai.com/api/v1/jobs/36abd4da-cf45-4bd0-... \
  -H "Authorization: Bearer sk-your-api-key"

When complete:

{
  "id": "36abd4da-cf45-4bd0-...",
  "status": "completed",
  "output_url": "https://assets.skystudios.app/gateway/music/.../result.mp3",
  "output_expires_at": "2026-05-09T00:00:00.000Z",
  "billed_credits": 30
}

Generate Parameters

The generate endpoint supports two modes: Simple Mode for quick generation from a text prompt, and Custom Mode for fine-grained control over lyrics, tempo, and language.

Simple Mode

Provide a short prompt describing the music you want. The gateway now auto-expands Simple Mode requests into a richer ACE music blueprint before worker submission, including compiled caption/lyrics structure and optional tempo metadata when useful.

Simple Mode is compiler-assisted. Custom Mode bypasses this expansion and lets you control prompt, lyrics, tempo, and language directly.

Compiler output is best-effort. If Vertex is unavailable or the compiler times out, the gateway falls back to the original Simple Mode request instead of failing the job.

Parameter	Type	Default	Description
`model`	string	`—`	Required. Currently: ace-step-1.5
`prompt`	string	`—`	Required. One-line music idea used as the Simple Mode source prompt.
`duration`	number	`30`	Duration in seconds (10–300). 1 credit per second.
`instrumental`	boolean	`false`	Gateway convenience field. Strongly biases Simple Mode toward instrumental structure and maps to [Instrumental] on fallback.

curl -X POST https://api.skystudioai.com/api/v1/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ace-step-1.5",
    "input": {
      "prompt": "chill lo-fi hip hop beats to study to",
      "duration": 30,
      "instrumental": true
    }
  }'

Custom Mode

Supply lyrics, tempo, and language for full control over the generation.

Parameter	Type	Default	Description
`model`	string	`—`	Required. Currently: ace-step-1.5
`prompt`	string	`—`	Required. Caption / song description
`lyrics`	string	`—`	Optional. Lyrics with section tags
`duration`	number	`30`	Duration in seconds (10–300). 1 credit per second.
`vocal_language`	string	`"en"`	Vocal language code
`bpm`	number	`—`	Optional. Tempo (30–300)
`seed`	number	`-1`	Random seed (-1 for random)
`instrumental`	boolean	`false`	Gateway convenience field. Overrides lyrics with [Instrumental] before worker submission.

curl -X POST https://api.skystudioai.com/api/v1/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ace-step-1.5",
    "input": {
      "prompt": "upbeat pop song with bright synths",
      "lyrics": "[verse]\nWalking through the city lights\nEverything feels so right\n[chorus]\nWe are the stars tonight",
      "duration": 60,
      "vocal_language": "en",
      "bpm": 120
    }
  }'

Custom Mode in this phase is Custom Lite. Reference audio upload, key/time signature, and batch size > 1 are deferred to a future release.

Job Statuses

`submitted`	Job accepted, queued for processing
`running`	Worker is generating output
`completed`	Done — output_url is available
`failed`	Generation failed — check error_message

SkyStudio · skystudioai.com