Compose Music with Details

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

Same compose body as POST /v1/music, plus optional with_timestamps and with_waveform_visual. Returns audio and metadata instead of a raw file only. Billed at $0.20 per generated minute.

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

Same fields as Compose music, plus:

Name	Type	Required	Description
with_timestamps	Boolean	No	Include word-level timestamps. Default false.
with_waveform_visual	Boolean	No	Include a visual waveform. Default false.

cURL Example

curl -X POST "https://api.knoxstudio.ai/v1/music/detailed?output_format=mp3_44100_128" \
     -H "Authorization: Bearer $KNOXCHAT_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
  "model_id": "music_v2_5",
  "prompt": "A cinematic orchestral theme",
  "music_length_ms": 30000,
  "with_timestamps": true
}'

Response

Success Response (200)

JSON (or multipart, depending on upstream) that includes the audio payload plus composition metadata. When with_timestamps is true, word timings are included.

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.