---
title: "Generate a music file"
method: POST
path: "/music"
tags: ["Music"]
---

# Generate a music file

`POST /music`

## Request

- Base URL: `https://api.braiv.co/v1`
- URL: `https://api.braiv.co/v1/music`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Queues a standalone music file from a text prompt and a duration in seconds. Does not mix the audio into a video. Costs 20 credits, refunded if generation fails. Required scope: `music:write`.

## Headers

- `Idempotency-Key` string

## Request body

- CreateMusicRequest
  - `prompt` string, required: Music description sent to generation unchanged.
  - `duration` number, required: Length of the music file in seconds.

## Response `202`

Music generation queued.

- CreateMusicResponse
  - `musicId` string, required: Music generation id.
  - `jobId` string, required: Pollable job id, `music_{musicId}`.
  - `creditsSpent` integer, required: Credits debited for this generation. Flat 20.
  - `balance` number, required: Billing-account balance after the debit.

## Other responses

- `400`: Request fields are missing, malformed, out of bounds, or mutually inconsistent.
- `401`: A supported authentication header is missing or contains an invalid Public API key.
- `403`: Authentication succeeded, but the required scope, workspace role, or resource permission is missing.
- `422`: Request fields are missing, malformed, out of bounds, or mutually inconsistent.
- `429`: The API key exceeded its allowed concurrency or request rate. Retry after in-flight work completes or the limit resets.
- `500`: An unexpected server error occurred.

---

[API](https://skmtc.dev/braiv/apis/braiv-public-api.md) - [All operations](https://skmtc.dev/braiv/apis/braiv-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/braiv/apis/braiv-public-api/revisions/8ed0fd0d0a6f?raw)