API reference · v1.0.0

Jammable API

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.

Get your API key
Base URLwww.jammable.com/api/v1
AuthBearer jmb_live_…
$0.05per minute of audio, less at volume
7 daysthen output files are deleted

Authentication

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

Authorization: Bearer jmb_live_your_api_key_here

Rate Limits

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

HeaderDescription
X-RateLimit-LimitRequests allowed per minute
X-RateLimit-RemainingRequests remaining in current window
X-RateLimit-ResetUnix 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 monthPrice 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.

Enterprise: for a custom rate, higher rate limits and concurrency, or paying by invoice, email [email protected].

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.

For AI agents

Point your coding agent at the Markdown version of this page, or plug the MCP server into Claude, Cursor or any MCP client and call the API as tools.

Voice Models

Browse and search the Jammable voice model catalog

GET/api/v1/models

Search voice models

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

Query

searchstring
Search by model name
categorystring · one of English, Spanish, Portuguese, Italian, German, Korean, Japanese, French, Music, Cartoon, Anime, Gaming, Public Figure, Other
Filter by category
sortstring · one of popular, trending, newest · default popular
Sort order
pageinteger · min 1 · default 1
Page number (starts at 1)
limitinteger · 1 to 100 · default 20
Results per page (max 100)
200 Paginated list of voice models400 Invalid request parameters401 Missing or invalid API key429 Rate limit exceeded
Response fields

200 Paginated list of voice models

dataobject[]
data[].idstring
Unique model ID
data[].namestring
Model display name
data[].url_paramstring
URL-friendly identifier (can be used as voice_model_id when creating covers)
data[].image_urlstring | null
Model image URL
data[].categoriesstring[]
Model categories
data[].descriptionstring | null
data[].total_usesinteger
Total number of covers made
data[].creatorobject | null
data[].creator.usernamestring
data[].creator.avatarstring
paginationobject
pagination.pageinteger
pagination.limitinteger
pagination.totalinteger
pagination.total_pagesinteger
curl "https://www.jammable.com/api/v1/models?search=deep-voice&limit=5" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY"

Response · 200

{
  "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
  }
}
GET/api/v1/models/{id}

Get voice model details

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

Path

idrequiredstring
Model ID or URL parameter (e.g. deep-voice)
200 Voice model details401 Missing or invalid API key404 Resource not found429 Rate limit exceeded
Response fields

200 Voice model details

dataobject
data.idstring
Unique model ID
data.namestring
Model display name
data.url_paramstring
URL-friendly identifier (can be used as voice_model_id when creating covers)
data.image_urlstring | null
Model image URL
data.categoriesstring[]
Model categories
data.descriptionstring | null
data.total_usesinteger
Total number of covers made
data.creatorobject | null
data.creator.usernamestring
data.creator.avatarstring
curl "https://www.jammable.com/api/v1/models/deep-voice" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY"

Response · 200

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

Covers

Create AI voice covers and check their status

POST/api/v1/covers

Create a cover

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.

Body

voice_model_idrequiredstring
ID or URL parameter of the voice model to use (e.g. 64abc123def... or deep-voice)
audio_urlrequiredurl
Publicly accessible URL to an audio file (MP3, WAV, etc.). YouTube and streaming links are not supported.
titlestring · max 200 chars
Optional title for the cover
pitch_semitonesinteger · -24 to 24 · default 0
Pitch shift in semitones (-24 to +24)
settingsobject
settings.voice_volumenumber · -10 to 10 · default 0
Voice volume adjustment in dB
settings.extract_backgroundboolean · default false
Extract and preserve background vocals
settings.vocals_onlyboolean · default false
Set when audio_url is already an a cappella (vocals only). Skips vocal separation
settings.autotuneobject
Snap the new vocal to the song's key. Send true for full strength, or an object to set the strength.
settings.autotune.strengthnumber · 0.2 to 1 · default 1
0.4 is light, 0.7 medium, 1 strong
settings.effect_idstring
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.mixobject
Mix controls on the vocals, applied after the effect preset. Whole numbers; leave a knob out to keep it at 0.
settings.mix.reverbinteger · 0 to 10 · default 0
settings.mix.echointeger · 0 to 10 · default 0
settings.mix.compressioninteger · 0 to 10 · default 0
settings.mix.bassinteger · -6 to 6 · default 0
dB at 150 Hz
settings.mix.trebleinteger · -6 to 6 · default 0
dB at 8 kHz
settings.choirobject
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.doublesstring · one of little, lot
settings.choir.harmoniesstring · one of little, lot
clipobject
Render only this window of the song. The output is duration_s long and you are billed for that length.
clip.start_srequirednumber · min 0
Start, in seconds of the source
clip.duration_srequirednumber · max 360
Length in seconds, up to 360
output_formatstring · one of mp3, wav · default mp3
wav returns every output file as stereo WAV instead of 320 kbps MP3
callback_urlurl
URL to receive a webhook when the cover completes or fails. Retried up to 3 times with exponential backoff on failure.
201 Cover creation started400 Invalid request parameters401 Missing or invalid API key402 Insufficient balance429 Rate limit exceeded
Response fields

201 Cover creation started

dataobject
data.idstring
Cover ID
data.short_idstring
Short ID (e.g. jam-a3b4c5d6)
data.statusstring · one of pending
data.created_atdate-time
data.expires_atdate-time
When output files will be deleted (7 days after creation)
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

{
  "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"
  }
}
GET/api/v1/covers

List your covers

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

Query

pageinteger · min 1 · default 1
limitinteger · 1 to 100 · default 20
statusstring · one of pending, processing, completed, failed
Filter by cover status
200 Paginated list of covers401 Missing or invalid API key429 Rate limit exceeded
Response fields

200 Paginated list of covers

dataobject[]
data[].idstring
data[].short_idstring
data[].titlestring | null
data[].statusstring · one of pending, processing, completed, failed
data[].progressinteger · 0 to 100
data[].voice_model_idstring | null
data[].output_urlsobject | null
Available only when status is completed. Files are deleted after expires_at.
data[].output_urls.audiostring | null
Final mixed audio
data[].output_urls.vocalsstring | null
Converted vocals only
data[].output_urls.instrumentalsstring | null
Instrumental track
data[].durationnumber | null
Duration in seconds
data[].created_atdate-time
data[].expires_atdate-time
When output files will be deleted (7 days after creation)
paginationobject
pagination.pageinteger
pagination.limitinteger
pagination.totalinteger
pagination.total_pagesinteger
curl "https://www.jammable.com/api/v1/covers" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY"

Response · 200

{
  "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
  }
}
GET/api/v1/covers/{id}

Get cover status

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

Path

idrequiredstring
Cover ID or short ID (e.g. jam-a3b4c5d6)
200 Cover details401 Missing or invalid API key404 Resource not found429 Rate limit exceeded
Response fields

200 Cover details

dataobject
data.idstring
data.short_idstring
data.titlestring | null
data.statusstring · one of pending, processing, completed, failed
data.progressinteger · 0 to 100
data.voice_model_idstring | null
data.output_urlsobject | null
Available only when status is completed. Files are deleted after expires_at.
data.output_urls.audiostring | null
Final mixed audio
data.output_urls.vocalsstring | null
Converted vocals only
data.output_urls.instrumentalsstring | null
Instrumental track
data.durationnumber | null
Duration in seconds
data.created_atdate-time
data.expires_atdate-time
When output files will be deleted (7 days after creation)
data.cover_settingsobject
data.cover_settings.pitch_semitonesinteger
data.cover_settings.extract_backgroundboolean
curl "https://www.jammable.com/api/v1/covers/jam-a3b4c5d6" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY"

Response · 200

{
  "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"
  }
}
GET/api/v1/effects

List effect presets

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.

No parameters.

200 Effect presets401 Missing or invalid API key429 Rate limit exceeded
curl "https://www.jammable.com/api/v1/effects" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY"

Response · 200

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

Jams

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

POST/api/v1/jams

Create a jam

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.

Body

voice_model_idsrequiredstring[]
Voices in slot order (ID or URL parameter). voice_times[].index points into this list.
audio_urlurl
Public audio file URL. Give this or source_cover_id.
source_cover_idstring
Reuse the source track of one of your covers or jams (ID or short ID) instead of audio_url.
voice_timesrequiredobject[]
Who sings when. Seconds of the source, or of the clip when clip is set.
voice_times[].indexrequiredinteger · min 0
Index into voice_model_ids
voice_times[].startrequirednumber · min 0
voice_times[].endrequirednumber · min 0
clipobject
Render only this window of the song. The output is duration_s long and you are billed for that length.
clip.start_srequirednumber · min 0
Start, in seconds of the source
clip.duration_srequirednumber · max 360
Length in seconds, up to 360
voice_pitchnumber[]
Pitch per voice in semitones, in the order of voice_model_ids. Missing entries are 0.
titlestring · max 200 chars
settingsobject
settings.voice_volumenumber · -10 to 10 · default 0
Voice volume adjustment in dB
settings.extract_backgroundboolean · default false
Extract and preserve background vocals
settings.vocals_onlyboolean · default false
Set when audio_url is already an a cappella (vocals only). Skips vocal separation
settings.autotuneobject
Snap the new vocal to the song's key. Send true for full strength, or an object to set the strength.
settings.autotune.strengthnumber · 0.2 to 1 · default 1
0.4 is light, 0.7 medium, 1 strong
settings.effect_idstring
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.mixobject
Mix controls on the vocals, applied after the effect preset. Whole numbers; leave a knob out to keep it at 0.
settings.mix.reverbinteger · 0 to 10 · default 0
settings.mix.echointeger · 0 to 10 · default 0
settings.mix.compressioninteger · 0 to 10 · default 0
settings.mix.bassinteger · -6 to 6 · default 0
dB at 150 Hz
settings.mix.trebleinteger · -6 to 6 · default 0
dB at 8 kHz
output_formatstring · one of mp3, wav · default mp3
wav returns every output file as stereo WAV instead of 320 kbps MP3
callback_urlurl
URL to receive a webhook when the jam completes or fails.
201 Job started400 Invalid request parameters401 Missing or invalid API key402 Insufficient balance429 Rate limit exceeded
Response fields

201 Job started

dataobject
data.idstring
data.short_idstring
data.statusstring · one of pending
data.created_atdate-time
data.expires_atdate-time
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

{
  "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"
  }
}
GET/api/v1/jams/{id}

Get jam status

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

Path

idrequiredstring
Jam ID or short ID (e.g. jam-a3b4c5d6)
200 Jam details401 Missing or invalid API key404 Resource not found429 Rate limit exceeded
curl "https://www.jammable.com/api/v1/jams/deep-voice" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY"

Response · 200

{
  "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"
  }
}

Uploads

Upload your own source audio

POST/api/v1/uploads

Upload a source track

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

Body

content_typerequiredstring · 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
filenamestring · max 200 chars
size_bytesinteger · max 209715200
Up to 200 MB
201 Upload URL400 Invalid request parameters401 Missing or invalid API key429 Rate limit exceeded
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

{
  "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
  }
}

Text to Speech

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

POST/api/v1/tts

Create a TTS cover

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.

Body

voice_model_idrequiredstring
ID or URL parameter of the voice model to use (e.g. 64abc123def... or deep-voice)
textrequiredstring · max 2500 chars
The text to convert to speech (max 2500 characters)
genderstring · one of male, female · default male
Voice gender for the TTS synthesis
accentstring · one of US, GB, FR, DE, ES, IT, KR, AU, JP · default US
Voice accent/language
expressionstring · one of Default, Whispered, Happy, Sad, Angry, Shouting, Terrified · default Default
Vocal expression style
speedstring · one of Slowest, Slow, Default, Fast, Fastest · default Default
Speech speed
titlestring · max 200 chars
Optional title for the cover
pitch_semitonesinteger · -24 to 24 · default 0
Pitch shift in semitones (-24 to +24)
settingsobject
settings.voice_volumenumber · -10 to 10 · default 0
Voice volume adjustment in dB
callback_urlurl
URL to receive a webhook when the cover completes or fails. Retried up to 3 times with exponential backoff on failure.
201 TTS cover creation started400 Invalid request parameters401 Missing or invalid API key402 Insufficient balance429 Rate limit exceeded
Response fields

201 TTS cover creation started

dataobject
data.idstring
Cover ID
data.short_idstring
Short ID (e.g. jam-a3b4c5d6)
data.statusstring · one of pending
data.created_atdate-time
data.expires_atdate-time
When output files will be deleted (7 days after creation)
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

{
  "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"
  }
}

Balance

Check your balance and add funds

GET/api/v1/credits

Get balance

Check your current API balance in USD.

No parameters.

200 Current balance401 Missing or invalid API key429 Rate limit exceeded
Response fields

200 Current balance

dataobject
data.balancenumber
Available balance in USD
curl "https://www.jammable.com/api/v1/credits" \
  -H "Authorization: Bearer $JAMMABLE_API_KEY"

Response · 200

{
  "data": {
    "balance": 48.5
  }
}
POST/api/v1/credits/checkout

Top up balance

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

Body

amountrequirednumber · min 10
Amount in USD to add to your balance (minimum $10)
200 Checkout session created400 Invalid request parameters401 Missing or invalid API key429 Rate limit exceeded
Response fields

200 Checkout session created

dataobject
data.checkout_urlurl
Stripe Checkout URL to complete payment
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

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