Compose Music

POST 
https://api.knoxstudio.ai/v1/music

Compose a song and return the audio file. Send prompt or composition_plan, not both. Billed at $0.20 per generated minute. Walkthrough: Music.

Request

Query Parameters

Name	Type	Required	Description
output_format	String	No	Default auto. Allowed: auto, mp3_48000_128, mp3_48000_192, mp3_48000_240, mp3_48000_320, mp3_22050_32, mp3_24000_48, mp3_44100_32, mp3_44100_64, mp3_44100_96, mp3_44100_128, mp3_44100_192, pcm_8000, pcm_16000, pcm_22050, pcm_24000, pcm_32000, pcm_44100, pcm_48000, ulaw_8000, alaw_8000, opus_48000_32, opus_48000_64, opus_48000_96, opus_48000_128, opus_48000_192.

Request Headers

Name	Type	Required	Description
Authorization	String	Yes	Bearer <token> Knox API key. xi-api-key is also accepted.
Content-Type	String	Yes	application/json.

Request Body

Name	Type	Required	Description
prompt	String	Conditional	Text prompt. Cannot be used with composition_plan.
composition_plan	Object	Conditional	Structured plan from POST /v1/music/plan. Cannot be used with prompt.
music_length_ms	Integer	No	Length in ms, 3000–300000. Only with prompt. Knox caps songs at 5 minutes.
model_id	String	No	music_v1 (default), music_v2, or music_v2_5.
seed	Integer	No	Determinism hint. Cannot be used with prompt.
force_instrumental	Boolean	No	If true, no vocals. Only with prompt. Default false.
finetune_id	String	No	Optional finetune from /v1/music/finetunes.
respect_sections_durations	Boolean	No	Enforce plan section durations. music_v1 only; ignored for v2 / v2.5. Default true.
store_for_inpainting	Boolean	No	Store the song for later inpainting. Default false.
sign_with_c2pa	Boolean	No	C2PA sign MP3 output. Default false.

cURL Example

curl -X POST "https://api.knoxstudio.ai/v1/music?output_format=mp3_44100_128" \
     -H "Authorization: Bearer $KNOXCHAT_API_KEY" \
     -H "Content-Type: application/json" \
     -o song.mp3 \
     -d '{
  "model_id": "music_v2_5",
  "prompt": "An upbeat indie-pop song about a night drive",
  "music_length_ms": 60000
}'

Response

Success Response (200)

The generated audio file. Content-Type follows output_format (default MP3). Song IDs used for inpainting are returned in response headers.

Billed at $0.20 per generated minute (prompt-only requests without music_length_ms are estimated at 30 seconds until the actual duration is known).

Error Responses

Validation uses HTTP 422:

{
  "detail": [
    {
      "loc": ["body", "field"],
      "msg": "…",
      "type": "value_error"
    }
  ]
}

Other errors use { "detail": "message" }.

Status	When
400	WebSocket path called without Upgrade: websocket.
401	Missing or invalid API key.
402	Insufficient credits.
403	Token is not allowed to use this model.
404	Resource not found.
422	Validation error.
429	Rate limit exceeded.
500	Internal server error.