Skip to main content
POST
Generate music
Generates music through one provider-independent API. Phaseo handles synchronous responses and provider queue polling behind the scenes. For completed generations, the response includes audio_url or audio_base64. If a provider returns a non-terminal job, use the same response id with GET /music/generate/{music_id}.

Request Shape

Suno Options

  • suno.customMode (boolean, default false)
  • suno.instrumental (boolean, default false)
  • suno.prompt (optional override for top-level prompt)
  • suno.style, suno.title (required when customMode = true)
  • suno.personaId, suno.personaModel
  • suno.negativeTags, suno.vocalGender
  • suno.styleWeight, suno.weirdnessConstraint, suno.audioWeight

Validation Rules

  • When customMode = false, prompt is required.
  • When customMode = true, both style and title are required.
  • When customMode = true and instrumental = false, prompt is required.
Validation errors return 400 with:

Response

  • id is the stable Phaseo request ID. Use it for retrieval through GET /music/generate/{music_id}.
  • nativeResponseId is the upstream provider’s identifier and is intended for provider correlation and support.
  • status can be queued, in_progress, completed, or failed.
  • usage can include output_audio_seconds when the provider reports generated duration.

Authorizations

Authorization
string
header
required

Bearer token authentication

Body

application/json
model
string
required
models
string[]

Optional ordered fallback models tried after model. model is required and is always the primary model. When an attempt fails with 429, 500, 502, 503, or 504, the next entry is tried; other errors are returned unchanged. Accepts up to 25 model IDs or presets; duplicates and entries equal to model are ignored. Each attempt is validated, logged, and billed as its own request, and the response model field and routing trace show the model that served the request. Streaming requests fall back only before the first byte, and video and music jobs fall back only at submission. Batch, realtime, and council requests reject models. Fallbacks set on a dynamic route take precedence, and phaseo/auto cannot be combined with models.

Required array length: 1 - 25 elements
Minimum string length: 1
Example:
prompt
string
duration
integer
format
enum<string>
Available options:
mp3,
wav,
ogg,
aac
provider
object

Provider routing preferences for gateway selection.

suno
object
elevenlabs
object
echo_upstream_request
boolean
debug
object

Gateway debug controls. These flags are never forwarded upstream.

Response

200 - application/json

Music generation response

id
string
required

Stable Phaseo request ID used with GET /music/generate/{music_id}.

object
enum<string>
required
Available options:
music
status
enum<string>
required
Available options:
queued,
in_progress,
completed,
failed
model
string
required
provider
string
required
nativeResponseId
string | null

Upstream provider identifier for correlation and support.

audio_url
string<uri>
audio_base64
string
result
any

Provider result metadata normalized by Phaseo.

output
object[]
usage
object
Last modified on October 18, 2026