# Jammable API reference

> Transform audio with AI voices programmatically. Use the Jammable API to search voice models, create voice conversions from audio files or text-to-speech, and retrieve results.

- Base URL: `https://www.jammable.com/api/v1`
- Auth: `Authorization: Bearer jmb_live_...` on every request. Get a key at https://www.jammable.com/developers/dashboard
- OpenAPI 3.1 spec: https://www.jammable.com/openapi.json
- MCP server (same API as tools): https://www.jammable.com/mcp.md
- Human-readable version: https://www.jammable.com/docs

Covers and text-to-speech are asynchronous: create the job, then poll `GET /api/v1/covers/{id}` until `status` is `completed` or `failed`, or pass a `callback_url`.

## Endpoints

- `GET /api/v1/models`: Search voice models ([details](#listmodels))
- `GET /api/v1/models/{id}`: Get voice model details ([details](#getmodel))
- `POST /api/v1/covers`: Create a cover ([details](#createcover))
- `GET /api/v1/covers`: List your covers ([details](#listcovers))
- `GET /api/v1/covers/{id}`: Get cover status ([details](#getcover))
- `GET /api/v1/effects`: List effect presets ([details](#listeffects))
- `POST /api/v1/jams`: Create a jam ([details](#createjam))
- `GET /api/v1/jams/{id}`: Get jam status ([details](#getjam))
- `POST /api/v1/uploads`: Upload a source track ([details](#createupload))
- `POST /api/v1/tts`: Create a TTS cover ([details](#createttscover))
- `GET /api/v1/credits`: Get balance ([details](#getcredits))
- `POST /api/v1/credits/checkout`: Top up balance ([details](#createcreditcheckout))

## Authentication

All requests require an API key passed via the `Authorization` header:

```
Authorization: Bearer jmb_live_your_api_key_here
```

## Get Started

You need an API key to make requests. Create one now:

> **[Open the Developer Dashboard →](https://www.jammable.com/developers/dashboard)**

## Rate Limits

Rate limits depend on your plan tier. Headers are included in every response:

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Requests allowed per minute |
| `X-RateLimit-Remaining` | Requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the window resets |

## Pricing

Usage is billed per minute of audio processed, by the second, and deducted from your balance after completion. Rates fall with your volume in the calendar month (UTC):

| Minutes this month | Price per minute |
|---|---|
| First 10,000 | $0.05 |
| 10,000 to 50,000 | $0.04 |
| Over 50,000 | $0.03 |

Each job has a $0.01 minimum. Failed jobs are not charged. Read operations (listing models, checking cover status) are free. Top up your balance via the checkout endpoint or the [Developer Dashboard](https://www.jammable.com/developers/dashboard).

**Enterprise:** for a custom rate, higher rate limits and concurrency, or paying by invoice, email [team@jammable.com](mailto:team@jammable.com?subject=Jammable%20API%20Enterprise).

## File Retention

Output audio files are automatically deleted **7 days** after creation. Download the files you need before the `expires_at` timestamp.

## Content Rights

You are responsible for ensuring you have the necessary rights to any audio content submitted for processing. Use of the API is subject to our [Terms of Service](https://www.jammable.com/terms).

## Voice Models

Browse and search the Jammable voice model catalog

### Search voice models

<a id="listmodels"></a>

```
GET /api/v1/models
```

Browse and search public voice models. Supports text search, category filtering, and sorting.

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `search` | string | no | Search by model name |
| `category` | string | no | Filter by category. one of `English`, `Spanish`, `Portuguese`, `Italian`, `German`, `Korean`, `Japanese`, `French`, `Music`, `Cartoon`, `Anime`, `Gaming`, `Public Figure`, `Other` |
| `sort` | string | no | Sort order. one of `popular`, `trending`, `newest`. default `popular` |
| `page` | integer | no | Page number (starts at 1). min 1. default `1` |
| `limit` | integer | no | Results per page (max 100). 1 to 100. default `20` |

**Example request**

```bash
curl "https://www.jammable.com/api/v1/models?search=deep-voice&limit=5" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY"
```

**Response 200**: Paginated list of voice models

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | object[] | no |  |
| `data[].id` | string | no | Unique model ID |
| `data[].name` | string | no | Model display name |
| `data[].url_param` | string | no | URL-friendly identifier (can be used as voice_model_id when creating covers) |
| `data[].image_url` | string | null | no | Model image URL |
| `data[].categories` | string[] | no | Model categories |
| `data[].description` | string | null | no |  |
| `data[].total_uses` | integer | no | Total number of covers made |
| `data[].creator` | object | null | no |  |
| `data[].creator.username` | string | no |  |
| `data[].creator.avatar` | string | no |  |
| `pagination` | object | no |  |
| `pagination.page` | integer | no |  |
| `pagination.limit` | integer | no |  |
| `pagination.total` | integer | no |  |
| `pagination.total_pages` | integer | no |  |

```json
{
  "data": [
    {
      "id": "64abc123def4567890abcdef",
      "name": "Deep Voice",
      "url_param": "deep-voice",
      "image_url": "https://images.jammable.com/models/deep-voice.jpg",
      "categories": [
        "English"
      ],
      "description": "A deep, resonant voice model",
      "total_uses": 150432,
      "creator": {
        "username": "jammable",
        "avatar": "https://images.jammable.com/avatars/jammable.jpg"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2847,
    "total_pages": 143
  }
}
```

**Errors**

- `400` `BAD_REQUEST`: Invalid request parameters
- `401` `UNAUTHORIZED`: Missing or invalid API key
- `429` `RATE_LIMITED`: Rate limit exceeded

### Get voice model details

<a id="getmodel"></a>

```
GET /api/v1/models/{id}
```

Retrieve details for a specific voice model by ID or URL parameter.

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Model ID or URL parameter (e.g. `deep-voice`) |

**Example request**

```bash
curl "https://www.jammable.com/api/v1/models/deep-voice" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY"
```

**Response 200**: Voice model details

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | object | no |  |
| `data.id` | string | no | Unique model ID |
| `data.name` | string | no | Model display name |
| `data.url_param` | string | no | URL-friendly identifier (can be used as voice_model_id when creating covers) |
| `data.image_url` | string | null | no | Model image URL |
| `data.categories` | string[] | no | Model categories |
| `data.description` | string | null | no |  |
| `data.total_uses` | integer | no | Total number of covers made |
| `data.creator` | object | null | no |  |
| `data.creator.username` | string | no |  |
| `data.creator.avatar` | string | no |  |

```json
{
  "data": {
    "id": "string",
    "name": "string",
    "url_param": "string",
    "image_url": "string",
    "categories": [
      "string"
    ],
    "description": "string",
    "total_uses": 0,
    "creator": {
      "username": "string",
      "avatar": "string"
    }
  }
}
```

**Errors**

- `401` `UNAUTHORIZED`: Missing or invalid API key
- `404` `NOT_FOUND`: Resource not found
- `429` `RATE_LIMITED`: Rate limit exceeded

## Covers

Create AI voice covers and check their status

### Create a cover

<a id="createcover"></a>

```
POST /api/v1/covers
```

Create an AI voice cover. This is an asynchronous operation — the cover will be processed in the background. Poll `GET /api/v1/covers/{id}` to check status, or provide a `callback_url` to receive a webhook when processing completes.

**Cost:** from $0.05 per minute of audio, less at volume (see Pricing), deducted after completion. Failed jobs are not charged.

**Retention:** Output audio files are deleted after 7 days.

**Request body** (JSON)

| Name | Type | Required | Description |
|---|---|---|---|
| `voice_model_id` | string | yes | ID or URL parameter of the voice model to use (e.g. `64abc123def...` or `deep-voice`) |
| `audio_url` | url | yes | Publicly accessible URL to an audio file (MP3, WAV, etc.). YouTube and streaming links are not supported. |
| `title` | string | no | Optional title for the cover. max 200 chars |
| `pitch_semitones` | integer | no | Pitch shift in semitones (-24 to +24). -24 to 24. default `0` |
| `settings` | object | no |  |
| `settings.voice_volume` | number | no | Voice volume adjustment in dB. -10 to 10. default `0` |
| `settings.extract_background` | boolean | no | Extract and preserve background vocals. default `false` |
| `settings.vocals_only` | boolean | no | Set when `audio_url` is already an a cappella (vocals only). Skips vocal separation. default `false` |
| `settings.autotune` | object | no | Snap the new vocal to the song's key. Send `true` for full strength, or an object to set the strength. |
| `settings.autotune.strength` | number | no | 0.4 is light, 0.7 medium, 1 strong. 0.2 to 1. default `1` |
| `settings.effect_id` | string | no | An effect preset from `GET /api/v1/effects`, by `id` or exact `name`. Some presets change only the vocals, others the whole song (for example sped up or slowed). |
| `settings.mix` | object | no | Mix controls on the vocals, applied after the effect preset. Whole numbers; leave a knob out to keep it at 0. |
| `settings.mix.reverb` | integer | no | 0 to 10. default `0` |
| `settings.mix.echo` | integer | no | 0 to 10. default `0` |
| `settings.mix.compression` | integer | no | 0 to 10. default `0` |
| `settings.mix.bass` | integer | no | dB at 150 Hz. -6 to 6. default `0` |
| `settings.mix.treble` | integer | no | dB at 8 kHz. -6 to 6. default `0` |
| `settings.choir` | object | no | Extra copies of the voice behind the lead. `doubles` adds two slightly detuned takes panned left and right; `harmonies` adds a third above and a third below along the song's scale. Each is `little` or `lot` (how loud and wide). Covers only. |
| `settings.choir.doubles` | string | no | one of `little`, `lot` |
| `settings.choir.harmonies` | string | no | one of `little`, `lot` |
| `clip` | object | no | Render only this window of the song. The output is `duration_s` long and you are billed for that length. |
| `clip.start_s` | number | yes | Start, in seconds of the source. min 0 |
| `clip.duration_s` | number | yes | Length in seconds, up to 360. max 360 |
| `output_format` | string | no | `wav` returns every output file as stereo WAV instead of 320 kbps MP3. one of `mp3`, `wav`. default `mp3` |
| `callback_url` | url | no | URL to receive a webhook when the cover completes or fails. Retried up to 3 times with exponential backoff on failure. |

```json
{
  "voice_model_id": "deep-voice",
  "audio_url": "https://example.com/audio.mp3",
  "title": "My AI Cover",
  "pitch_semitones": 0,
  "settings": {
    "voice_volume": 0,
    "extract_background": false,
    "autotune": {
      "strength": 0.7
    },
    "mix": {
      "reverb": 4,
      "compression": 3
    },
    "choir": {
      "harmonies": "little"
    }
  },
  "output_format": "wav",
  "callback_url": "https://myapp.com/webhook/cover-complete"
}
```

**Example request**

```bash
curl -X POST "https://www.jammable.com/api/v1/covers" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_model_id": "deep-voice",
    "audio_url": "https://example.com/audio.mp3",
    "title": "My AI Cover",
    "pitch_semitones": 0,
    "settings": {
      "voice_volume": 0,
      "extract_background": false,
      "autotune": {
        "strength": 0.7
      },
      "mix": {
        "reverb": 4,
        "compression": 3
      },
      "choir": {
        "harmonies": "little"
      }
    },
    "output_format": "wav",
    "callback_url": "https://myapp.com/webhook/cover-complete"
  }'
```

**Response 201**: Cover creation started

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | object | no |  |
| `data.id` | string | no | Cover ID |
| `data.short_id` | string | no | Short ID (e.g. jam-a3b4c5d6) |
| `data.status` | string | no | one of `pending` |
| `data.created_at` | date-time | no |  |
| `data.expires_at` | date-time | no | When output files will be deleted (7 days after creation) |

```json
{
  "data": {
    "id": "65def456abc7890123456789",
    "short_id": "jam-a3b4c5d6",
    "status": "pending",
    "created_at": "2025-03-15T14:30:00.000Z",
    "expires_at": "2025-03-22T14:30:00.000Z"
  }
}
```

**Errors**

- `400` `BAD_REQUEST`: Invalid request parameters
- `401` `UNAUTHORIZED`: Missing or invalid API key
- `402` `INSUFFICIENT_BALANCE`: Insufficient balance
- `429` `RATE_LIMITED`: Rate limit exceeded

### List your covers

<a id="listcovers"></a>

```
GET /api/v1/covers
```

List all covers created with your API key, ordered by most recent first.

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | no | min 1. default `1` |
| `limit` | integer | no | 1 to 100. default `20` |
| `status` | string | no | Filter by cover status. one of `pending`, `processing`, `completed`, `failed` |

**Example request**

```bash
curl "https://www.jammable.com/api/v1/covers" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY"
```

**Response 200**: Paginated list of covers

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | object[] | no |  |
| `data[].id` | string | no |  |
| `data[].short_id` | string | no |  |
| `data[].title` | string | null | no |  |
| `data[].status` | string | no | one of `pending`, `processing`, `completed`, `failed` |
| `data[].progress` | integer | no | 0 to 100 |
| `data[].voice_model_id` | string | null | no |  |
| `data[].output_urls` | object | null | no | Available only when status is `completed`. Files are deleted after `expires_at`. |
| `data[].output_urls.audio` | string | null | no | Final mixed audio |
| `data[].output_urls.vocals` | string | null | no | Converted vocals only |
| `data[].output_urls.instrumentals` | string | null | no | Instrumental track |
| `data[].duration` | number | null | no | Duration in seconds |
| `data[].created_at` | date-time | no |  |
| `data[].expires_at` | date-time | no | When output files will be deleted (7 days after creation) |
| `pagination` | object | no |  |
| `pagination.page` | integer | no |  |
| `pagination.limit` | integer | no |  |
| `pagination.total` | integer | no |  |
| `pagination.total_pages` | integer | no |  |

```json
{
  "data": [
    {
      "id": "string",
      "short_id": "string",
      "title": "string",
      "status": "pending",
      "progress": 0,
      "voice_model_id": "string",
      "output_urls": {
        "audio": "string",
        "vocals": "string",
        "instrumentals": "string"
      },
      "duration": 0,
      "created_at": "2025-03-15T14:30:00.000Z",
      "expires_at": "2025-03-15T14:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 0,
    "limit": 0,
    "total": 0,
    "total_pages": 0
  }
}
```

**Errors**

- `401` `UNAUTHORIZED`: Missing or invalid API key
- `429` `RATE_LIMITED`: Rate limit exceeded

### Get cover status

<a id="getcover"></a>

```
GET /api/v1/covers/{id}
```

Check the status and results of a cover. When status is `completed`, `output_urls` will contain the audio files.

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Cover ID or short ID (e.g. `jam-a3b4c5d6`) |

**Example request**

```bash
curl "https://www.jammable.com/api/v1/covers/jam-a3b4c5d6" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY"
```

**Response 200**: Cover details

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | object | no |  |
| `data.id` | string | no |  |
| `data.short_id` | string | no |  |
| `data.title` | string | null | no |  |
| `data.status` | string | no | one of `pending`, `processing`, `completed`, `failed` |
| `data.progress` | integer | no | 0 to 100 |
| `data.voice_model_id` | string | null | no |  |
| `data.output_urls` | object | null | no | Available only when status is `completed`. Files are deleted after `expires_at`. |
| `data.output_urls.audio` | string | null | no | Final mixed audio |
| `data.output_urls.vocals` | string | null | no | Converted vocals only |
| `data.output_urls.instrumentals` | string | null | no | Instrumental track |
| `data.duration` | number | null | no | Duration in seconds |
| `data.created_at` | date-time | no |  |
| `data.expires_at` | date-time | no | When output files will be deleted (7 days after creation) |
| `data.cover_settings` | object | no |  |
| `data.cover_settings.pitch_semitones` | integer | no |  |
| `data.cover_settings.extract_background` | boolean | no |  |

```json
{
  "data": {
    "id": "65def456abc7890123456789",
    "short_id": "jam-a3b4c5d6",
    "title": "My AI Cover",
    "status": "completed",
    "progress": 100,
    "voice_model_id": "64abc123def4567890abcdef",
    "output_urls": {
      "audio": "https://audio.jammable.com/covers/combined.mp3",
      "vocals": "https://audio.jammable.com/covers/vocals.mp3",
      "instrumentals": "https://audio.jammable.com/covers/instrumentals.mp3"
    },
    "duration": 215.4,
    "cover_settings": {
      "pitch_semitones": 0,
      "extract_background": false
    },
    "created_at": "2025-03-15T14:30:00.000Z",
    "expires_at": "2025-03-22T14:30:00.000Z"
  }
}
```

**Errors**

- `401` `UNAUTHORIZED`: Missing or invalid API key
- `404` `NOT_FOUND`: Resource not found
- `429` `RATE_LIMITED`: Rate limit exceeded

### List effect presets

<a id="listeffects"></a>

```
GET /api/v1/effects
```

The effect presets a cover or jam can use as `settings.effect_id`, most used first. `applies_to` is `vocals` (changes only the voice) or `song` (changes the whole track, for example sped up or slowed). Free.

**Example request**

```bash
curl "https://www.jammable.com/api/v1/effects" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY"
```

**Response 200**: Effect presets

```json
{
  "data": [
    {
      "id": "6650a1b2c3d4e5f607182930",
      "name": "Slow and Reverb",
      "description": "Slowed down with a big room",
      "emoji": "🌙",
      "applies_to": "song"
    }
  ]
}
```

**Errors**

- `401` `UNAUTHORIZED`: Missing or invalid API key
- `429` `RATE_LIMITED`: Rate limit exceeded

## Jams

Covers sung by several voices, with you deciding who sings when

### Create a jam

<a id="createjam"></a>

```
POST /api/v1/jams
```

A cover sung by several voices, where you decide who sings when. Give the voices in order and `voice_times` as index, start and end. Poll `GET /api/v1/jams/{id}`, or pass `callback_url`.

**Cost:** billed per minute of output like a cover, however many voices sing.

**Request body** (JSON)

| Name | Type | Required | Description |
|---|---|---|---|
| `voice_model_ids` | string[] | yes | Voices in slot order (ID or URL parameter). `voice_times[].index` points into this list. |
| `audio_url` | url | no | Public audio file URL. Give this or `source_cover_id`. |
| `source_cover_id` | string | no | Reuse the source track of one of your covers or jams (ID or short ID) instead of `audio_url`. |
| `voice_times` | object[] | yes | Who sings when. Seconds of the source, or of the clip when `clip` is set. |
| `voice_times[].index` | integer | yes | Index into `voice_model_ids`. min 0 |
| `voice_times[].start` | number | yes | min 0 |
| `voice_times[].end` | number | yes | min 0 |
| `clip` | object | no | Render only this window of the song. The output is `duration_s` long and you are billed for that length. |
| `clip.start_s` | number | yes | Start, in seconds of the source. min 0 |
| `clip.duration_s` | number | yes | Length in seconds, up to 360. max 360 |
| `voice_pitch` | number[] | no | Pitch per voice in semitones, in the order of `voice_model_ids`. Missing entries are 0. |
| `title` | string | no | max 200 chars |
| `settings` | object | no |  |
| `settings.voice_volume` | number | no | Voice volume adjustment in dB. -10 to 10. default `0` |
| `settings.extract_background` | boolean | no | Extract and preserve background vocals. default `false` |
| `settings.vocals_only` | boolean | no | Set when `audio_url` is already an a cappella (vocals only). Skips vocal separation. default `false` |
| `settings.autotune` | object | no | Snap the new vocal to the song's key. Send `true` for full strength, or an object to set the strength. |
| `settings.autotune.strength` | number | no | 0.4 is light, 0.7 medium, 1 strong. 0.2 to 1. default `1` |
| `settings.effect_id` | string | no | An effect preset from `GET /api/v1/effects`, by `id` or exact `name`. Some presets change only the vocals, others the whole song (for example sped up or slowed). |
| `settings.mix` | object | no | Mix controls on the vocals, applied after the effect preset. Whole numbers; leave a knob out to keep it at 0. |
| `settings.mix.reverb` | integer | no | 0 to 10. default `0` |
| `settings.mix.echo` | integer | no | 0 to 10. default `0` |
| `settings.mix.compression` | integer | no | 0 to 10. default `0` |
| `settings.mix.bass` | integer | no | dB at 150 Hz. -6 to 6. default `0` |
| `settings.mix.treble` | integer | no | dB at 8 kHz. -6 to 6. default `0` |
| `output_format` | string | no | `wav` returns every output file as stereo WAV instead of 320 kbps MP3. one of `mp3`, `wav`. default `mp3` |
| `callback_url` | url | no | URL to receive a webhook when the jam completes or fails. |

```json
{
  "voice_model_ids": [
    "deep-voice",
    "bright-voice"
  ],
  "audio_url": "https://example.com/audio.mp3",
  "voice_times": [
    {
      "index": 0,
      "start": 0,
      "end": 15.5
    },
    {
      "index": 1,
      "start": 15.5,
      "end": 31
    }
  ],
  "clip": {
    "start_s": 30,
    "duration_s": 31
  },
  "voice_pitch": [
    0,
    4
  ],
  "settings": {
    "mix": {
      "reverb": 3
    }
  }
}
```

**Example request**

```bash
curl -X POST "https://www.jammable.com/api/v1/jams" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_model_ids": [
      "deep-voice",
      "bright-voice"
    ],
    "audio_url": "https://example.com/audio.mp3",
    "voice_times": [
      {
        "index": 0,
        "start": 0,
        "end": 15.5
      },
      {
        "index": 1,
        "start": 15.5,
        "end": 31
      }
    ],
    "clip": {
      "start_s": 30,
      "duration_s": 31
    },
    "voice_pitch": [
      0,
      4
    ],
    "settings": {
      "mix": {
        "reverb": 3
      }
    }
  }'
```

**Response 201**: Job started

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | object | no |  |
| `data.id` | string | no |  |
| `data.short_id` | string | no |  |
| `data.status` | string | no | one of `pending` |
| `data.created_at` | date-time | no |  |
| `data.expires_at` | date-time | no |  |

```json
{
  "data": {
    "id": "65def456abc7890123456789",
    "short_id": "jam-a3b4c5d6",
    "status": "pending",
    "created_at": "2025-03-15T14:30:00.000Z",
    "expires_at": "2025-03-22T14:30:00.000Z"
  }
}
```

**Errors**

- `400` `BAD_REQUEST`: Invalid request parameters
- `401` `UNAUTHORIZED`: Missing or invalid API key
- `402` `INSUFFICIENT_BALANCE`: Insufficient balance
- `429` `RATE_LIMITED`: Rate limit exceeded

### Get jam status

<a id="getjam"></a>

```
GET /api/v1/jams/{id}
```

Status and results of a jam. When status is `completed`, `output_urls` has the full mix, the vocals and the instrumental.

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Jam ID or short ID (e.g. `jam-a3b4c5d6`) |

**Example request**

```bash
curl "https://www.jammable.com/api/v1/jams/deep-voice" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY"
```

**Response 200**: Jam details

```json
{
  "data": {
    "id": "65def456abc7890123456789",
    "short_id": "jam-a3b4c5d6",
    "title": "My jam",
    "status": "completed",
    "progress": 100,
    "voice_model_ids": [
      "64abc123def4567890abcdef",
      "64abc123def4567890abcdee"
    ],
    "voice_times": [
      {
        "voice": "deep-voice",
        "start": 0,
        "end": 15.5
      },
      {
        "voice": "bright-voice",
        "start": 15.5,
        "end": 31
      }
    ],
    "output_urls": {
      "audio": "https://audio.jammable.com/jammer/.../combined.mp3",
      "vocals": "https://audio.jammable.com/jammer/.../vocals.mp3",
      "instrumentals": "https://audio.jammable.com/jammer/.../instrumentals.mp3"
    },
    "duration": 31,
    "created_at": "2025-03-15T14:30:00.000Z",
    "expires_at": "2025-03-22T14:30:00.000Z"
  }
}
```

**Errors**

- `401` `UNAUTHORIZED`: Missing or invalid API key
- `404` `NOT_FOUND`: Resource not found
- `429` `RATE_LIMITED`: Rate limit exceeded

## Uploads

Upload your own source audio

### Upload a source track

<a id="createupload"></a>

```
POST /api/v1/uploads
```

Get a presigned URL to upload an audio file straight to Jammable storage, then use the returned `audio_url` with `POST /api/v1/covers` or `POST /api/v1/jams`. Send the file with `PUT` to `upload_url`, with the `Content-Type` header given, within `expires_in` seconds. Works from browsers (CORS is allowed).

**Request body** (JSON)

| Name | Type | Required | Description |
|---|---|---|---|
| `content_type` | string | yes | one of `audio/mpeg`, `audio/mp3`, `audio/wav`, `audio/x-wav`, `audio/wave`, `audio/mp4`, `audio/x-m4a`, `audio/aac`, `audio/ogg`, `audio/flac`, `audio/webm` |
| `filename` | string | no | max 200 chars |
| `size_bytes` | integer | no | Up to 200 MB. max 209715200 |

```json
{
  "content_type": "audio/mpeg",
  "filename": "song.mp3"
}
```

**Example request**

```bash
curl -X POST "https://www.jammable.com/api/v1/uploads" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content_type": "audio/mpeg",
    "filename": "song.mp3"
  }'
```

**Response 201**: Upload URL

```json
{
  "data": {
    "upload_url": "https://...r2.cloudflarestorage.com/audio/api-uploads/...",
    "method": "PUT",
    "headers": {
      "Content-Type": "audio/mpeg"
    },
    "audio_url": "https://audio.jammable.com/api-uploads/.../file.mp3",
    "expires_in": 900
  }
}
```

**Errors**

- `400` `BAD_REQUEST`: Invalid request parameters
- `401` `UNAUTHORIZED`: Missing or invalid API key
- `429` `RATE_LIMITED`: Rate limit exceeded

## Text to Speech

Create AI voice covers from text input using text-to-speech

### Create a TTS cover

<a id="createttscover"></a>

```
POST /api/v1/tts
```

Create an AI voice cover from text using text-to-speech. The text is first synthesized into speech audio, then processed through the selected voice model.

This is an asynchronous operation — the cover will be processed in the background. Poll `GET /api/v1/covers/{id}` to check status, or provide a `callback_url` to receive a webhook when processing completes.

**Cost:** from $0.05 per minute of audio, less at volume (see Pricing), deducted after completion. Failed jobs are not charged.

**Retention:** Output audio files are deleted after 7 days.

**Request body** (JSON)

| Name | Type | Required | Description |
|---|---|---|---|
| `voice_model_id` | string | yes | ID or URL parameter of the voice model to use (e.g. `64abc123def...` or `deep-voice`) |
| `text` | string | yes | The text to convert to speech (max 2500 characters). max 2500 chars |
| `gender` | string | no | Voice gender for the TTS synthesis. one of `male`, `female`. default `male` |
| `accent` | string | no | Voice accent/language. one of `US`, `GB`, `FR`, `DE`, `ES`, `IT`, `KR`, `AU`, `JP`. default `US` |
| `expression` | string | no | Vocal expression style. one of `Default`, `Whispered`, `Happy`, `Sad`, `Angry`, `Shouting`, `Terrified`. default `Default` |
| `speed` | string | no | Speech speed. one of `Slowest`, `Slow`, `Default`, `Fast`, `Fastest`. default `Default` |
| `title` | string | no | Optional title for the cover. max 200 chars |
| `pitch_semitones` | integer | no | Pitch shift in semitones (-24 to +24). -24 to 24. default `0` |
| `settings` | object | no |  |
| `settings.voice_volume` | number | no | Voice volume adjustment in dB. -10 to 10. default `0` |
| `callback_url` | url | no | URL to receive a webhook when the cover completes or fails. Retried up to 3 times with exponential backoff on failure. |

```json
{
  "voice_model_id": "deep-voice",
  "text": "Hello, this is a test of the text to speech system.",
  "gender": "male",
  "accent": "US",
  "expression": "Default",
  "speed": "Default",
  "title": "My TTS Cover",
  "callback_url": "https://myapp.com/webhook/cover-complete"
}
```

**Example request**

```bash
curl -X POST "https://www.jammable.com/api/v1/tts" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_model_id": "deep-voice",
    "text": "Hello, this is a test of the text to speech system.",
    "gender": "male",
    "accent": "US",
    "expression": "Default",
    "speed": "Default",
    "title": "My TTS Cover",
    "callback_url": "https://myapp.com/webhook/cover-complete"
  }'
```

**Response 201**: TTS cover creation started

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | object | no |  |
| `data.id` | string | no | Cover ID |
| `data.short_id` | string | no | Short ID (e.g. jam-a3b4c5d6) |
| `data.status` | string | no | one of `pending` |
| `data.created_at` | date-time | no |  |
| `data.expires_at` | date-time | no | When output files will be deleted (7 days after creation) |

```json
{
  "data": {
    "id": "65def456abc7890123456789",
    "short_id": "jam-a3b4c5d6",
    "status": "pending",
    "created_at": "2025-03-15T14:30:00.000Z",
    "expires_at": "2025-03-22T14:30:00.000Z"
  }
}
```

**Errors**

- `400` `BAD_REQUEST`: Invalid request parameters
- `401` `UNAUTHORIZED`: Missing or invalid API key
- `402` `INSUFFICIENT_BALANCE`: Insufficient balance
- `429` `RATE_LIMITED`: Rate limit exceeded

## Balance

Check your balance and add funds

### Get balance

<a id="getcredits"></a>

```
GET /api/v1/credits
```

Check your current API balance in USD.

**Example request**

```bash
curl "https://www.jammable.com/api/v1/credits" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY"
```

**Response 200**: Current balance

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | object | no |  |
| `data.balance` | number | no | Available balance in USD |

```json
{
  "data": {
    "balance": 48.5
  }
}
```

**Errors**

- `401` `UNAUTHORIZED`: Missing or invalid API key
- `429` `RATE_LIMITED`: Rate limit exceeded

### Top up balance

<a id="createcreditcheckout"></a>

```
POST /api/v1/credits/checkout
```

Create a Stripe Checkout session to add funds to your API balance. Returns a checkout URL to complete payment.

**Request body** (JSON)

| Name | Type | Required | Description |
|---|---|---|---|
| `amount` | number | yes | Amount in USD to add to your balance (minimum $10). min 10 |

```json
{
  "amount": 50
}
```

**Example request**

```bash
curl -X POST "https://www.jammable.com/api/v1/credits/checkout" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50
  }'
```

**Response 200**: Checkout session created

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | object | no |  |
| `data.checkout_url` | url | no | Stripe Checkout URL to complete payment |

```json
{
  "data": {
    "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_..."
  }
}
```

**Errors**

- `400` `BAD_REQUEST`: Invalid request parameters
- `401` `UNAUTHORIZED`: Missing or invalid API key
- `429` `RATE_LIMITED`: Rate limit exceeded

## Error format

Every error has the same shape. Branch on `error.code`, not on the message.

```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded.",
    "details": {
      "retry_after": 45
    }
  }
}
```
