> ## 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.

# Upload a voice recording

> Save and prepare one vocal recording.

Send text fields before the file. An uploaded full mix is not automatically converted to isolated vocals. Saving and trained readiness are separate states.

[Voice upload and readiness](/dev/guides/generate/voices).

## 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" required>
  Selected account address. Required for owner-scoped reads and writes. It identifies the account; your product must authenticate its own users.
</ParamField>

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

## Multipart body

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

<ParamField body="name" type="string" />

<ParamField body="file" type="file" required>
  One WAV, MP3, FLAC, OGG, AAC, M4A/MP4 or WebM recording. Maximum 50 MiB. For preparation, use mono/stereo audio up to 240 seconds.
</ParamField>

## Response (202)

Accepted; follow the returned task.

<ResponseField name="success" type="boolean" required />

<ResponseField name="voice" type="object" required>
  <Expandable title="Properties">
    <ResponseField name="id" type="string" required />

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

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

    <ResponseField name="sample_url" type="string | null" />

    <ResponseField name="source_song_id" type="string | null" />

    <ResponseField name="status" type="string" required>
      Values: `saved`, `extracting`, `queued`, `training`, `ready`, `error`.
    </ResponseField>

    <ResponseField name="error" type="string | null" />

    <ResponseField name="availability" type="object">
      <Expandable title="Properties">
        <ResponseField name="turbo" type="object">
          <Expandable title="Properties">
            <ResponseField name="model" type="string" />

            <ResponseField name="status" type="string">
              Check ready for the generation mode you will use.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="sft" type="object">
          <Expandable title="Properties">
            <ResponseField name="model" type="string" />

            <ResponseField name="status" type="string">
              Check ready for the generation mode you will use.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

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. |
| `403` | Account does not match resource. |
| `404` | Resource not found. |
| `409` | Resource conflict; reload state or open an editable version. |
| `500` | Request failed. |

<RequestExample>
  ```bash cURL theme={null}
  curl --fail-with-body -X POST "$RAWCHUNKS_API/api/voices/upload" \
    -H "Authorization: Bearer $SESSION_TOKEN" \
    -H "x-network-id: $NETWORK" \
    -H "x-session-user-address: $USER_ADDRESS" \
    -F "creator=$USER_ADDRESS" \
    -F "name=Lead voice" \
    -F "file=@voice.wav;type=audio/wav"
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "voice": {
      "id": "voice-example",
      "name": "Lead voice",
      "creator": "0x1111111111111111111111111111111111111111",
      "status": "saved"
    }
  }
  ```
</ResponseExample>


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