> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rawchunks.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate music

> Submit a new music generation.

Fast (`turbo`) costs \$0.05. Studio Master (`sft`) costs \$0.10. `creatorAddress` can be omitted when the selected account comes from the session, but explicit addresses must match your intended creator. New songs start private.

[Generate and retrieve audio](/dev/guides/generate/music).

## Headers and parameters

<ParamField header="Authorization" type="string" required>
  `Bearer $SESSION_TOKEN`. Use the complete token from your active [Rawchunks session](/dev/guides/payments).
</ParamField>

<ParamField header="x-session-user-address" type="string">
  Session owner address. Supplies `creatorAddress` when omitted from the JSON body.
</ParamField>

<ParamField header="x-network-id" type="string">
  Session network in CAIP-2 form, for example eip155:8453.
</ParamField>

## JSON body

<ParamField body="creatorAddress" type="string">
  Wallet address for the selected account. Use the same address as the session owner. Minimum length: `10`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Musical description. At least three characters after trimming. Minimum length: `3`.
</ParamField>

<ParamField body="modelVariant" type="string" default={"turbo"}>
  Fast or Studio Master. Values: `turbo`, `sft`.
</ParamField>

<ParamField body="title" type="string">
  Omit or leave blank for an Untitled title.
</ParamField>

<ParamField body="image" type="string">
  Artwork URL.
</ParamField>

<ParamField body="albumId" type="string">
  Existing album ID.
</ParamField>

<ParamField body="lyrics" type="string">
  Plain text with optional section tags. Omit for automatic lyrics/settings; specify instrumental for no vocals.
</ParamField>

<ParamField body="instrumental" type="boolean">
  When true, the request uses \[Instrumental] lyrics.
</ParamField>

<ParamField body="vocalLanguage" type="string">
  Language ID from GET /api/options.
</ParamField>

<ParamField body="bpm" type="number">
  Tempo in beats per minute. Range: `30` to `300`.
</ParamField>

<ParamField body="keyScale" type="string">
  Key ID from GET /api/options.
</ParamField>

<ParamField body="audioDuration" type="number">
  Requested duration in seconds. Range: `5` to `300`.
</ParamField>

<ParamField body="seed" type="integer">
  Optional seed. Omit for a random seed; this is not a guarantee of byte-identical audio. Range: `0` to `9007199254740991`.
</ParamField>

<ParamField body="voiceId" type="string">
  Opaque ID returned by the API. Minimum length: `1`.
</ParamField>

<ParamField body="voiceMode" type="string">
  Required with voiceId. Trained mode needs a ready saved voice for the selected model. Values: `reference`, `trained`.
</ParamField>

<ParamField body="voiceReferenceUrl" type="string">
  Direct reference audio URL. Mutually exclusive with voiceId.
</ParamField>

<ParamField body="voiceCoverStrength" type="number">
  Voice conditioning strength. Default 0.7 for saved voices, 0.65 for direct references. Range: `0` to `1`.
</ParamField>

<ParamField body="tags" type="string[]" />

<ParamField body="licenses" type="integer" default={0}>
  Listed allocation. Omitted value is 0. Minimum: `0`.
</ParamField>

<ParamField body="stream_price" type="number" default={0.02}>
  Listed USDC per minute. Separate from the service fee. Minimum: `0`.
</ParamField>

<ParamField body="license_price" type="number" default={25}>
  Listed USDC per license. Separate from the service fee. Minimum: `0`.
</ParamField>

## Response (202)

Accepted; follow the returned task.

<ResponseField name="songId" type="string" required />

<ResponseField name="taskId" type="string" required />

<ResponseField name="status" type="string" required>
  Values: `pending`, `processing`, `ready`.
</ResponseField>

<ResponseField name="model" type="string" />

<ResponseField name="steps" type="integer" />

<ResponseField name="lyrics" type="string" />

Budget headers use six-decimal USDC atomic units. See [session payments](/dev/guides/payments#track-or-end-a-session).

## Errors

Failed JSON responses contain an `error` string. Check the HTTP status before reading a successful result. See [job handling](/dev/guides/jobs) for interrupted or uncertain submissions.

| Status | Meaning |
| - | - |
| `400` | Invalid request. |
| `401` | Invalid or expired session token. |
| `402` | Payment required or insufficient session budget. |
| `500` | Request failed. |

<RequestExample>
  ```bash cURL theme={null}
  curl --fail-with-body -X POST "$RAWCHUNKS_API/api/generation/generate" \
    -H "Authorization: Bearer $SESSION_TOKEN" \
    -H "x-session-user-address: $USER_ADDRESS" \
    -H "x-network-id: $NETWORK" \
    -H "Content-Type: application/json" \
    --data "$(jq -nc --arg user "$USER_ADDRESS" '{
    "creatorAddress": $user,
    "prompt": "Instrumental acid house with a dry kick, rolling bass and a restrained synth lead",
    "instrumental": true,
    "audioDuration": 60,
    "bpm": 124,
    "modelVariant": "turbo",
    "title": "Night circuit",
    "licenses": 20,
    "license_price": 5,
    "stream_price": 0.01
  }')"
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "songId": "sng-example",
    "taskId": "task-example",
    "status": "pending"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.