API Documentation

Our api domain is https://api.treblo.com/v1. This is v1 of our API specification. Model versions are specified in the endpoint like: https://api.treblo.com/v1/generations/v2 or https://api.treblo.com/v1/generations/v3.

Base URL:https://api.treblo.com/v1

Quick Start

Generate your first song with the Treblo API in minutes.

Prompt

curl -X POST https://api.treblo.com/v1/generations/v3 \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "a chill lofi beat for studying" }'

Response

The API returns a task ID that you can use to poll for the result.

json

{
  "task_id": "abc123-def456-ghi789"
}

Polling for Results

After submitting a generation request, poll the status endpoint until the task completes. Alternatively, you can pass a webhook_url in your request to receive status updates automatically.

# Poll until the task completes
while true; do
  STATUS=$(curl -s https://api.treblo.com/v1/generations/status/abc123-def456-ghi789 \
    -H "Authorization: Bearer your_api_key_here" | jq -r '.status')
  echo "Status: $STATUS"

  if [ "$STATUS" = "SUCCESS" ]; then
    break
  elif [ "$STATUS" = "FAILURE" ]; then
    echo "Generation failed"
    exit 1
  fi

  sleep 5
done

# Fetch the completed generation
curl https://api.treblo.com/v1/generations/abc123-def456-ghi789 \
  -H "Authorization: Bearer your_api_key_here"

Complete Example

End-to-end flow: generate a song, poll until complete, and retrieve the audio URL.

# 1. Start generation (prompt only — tags are inferred)
TASK_ID=$(curl -s -X POST https://api.treblo.com/v1/generations/v3 \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "a chill lofi beat for studying"
}' | jq -r '.task_id')
echo "Generation started: $TASK_ID"

# 2. Poll for completion
while true; do
  STATUS=$(curl -s https://api.treblo.com/v1/generations/status/$TASK_ID \
    -H "Authorization: Bearer your_api_key_here" | jq -r '.status')
  echo "  Status: $STATUS"

  if [ "$STATUS" = "SUCCESS" ]; then break; fi
  if [ "$STATUS" = "FAILURE" ]; then echo "Failed!"; exit 1; fi
  sleep 5
done

# 3. Get the audio URL
curl -s https://api.treblo.com/v1/generations/$TASK_ID \
  -H "Authorization: Bearer your_api_key_here" | jq '.song_paths[0]'

Authentication

All endpoints require an API key to be passed in the Authorization header:

Authorization: Bearer your_api_key_here

Generation Endpoints

Every v3 request (generate, extend, inpaint, reference) costs 100 credits. Streaming does not change the cost.

Core Parameters

Recommended: start with just a prompt

The best results come from sending only prompt and letting our model infer tags, lyrics, and strength settings for you. Avoid manually setting tags or any strength values unless you have a specific reason to override the defaults.

For all generation endpoints, you must provide at least one of tags, lyrics, or prompt. If tags or lyrics is left blank (or omitted), it will be generated by AI based on the prompt — this is what we recommend. You can view a list of supported tags on our Styles page, but you typically do not need to send them yourself.
If you do pass tags explicitly, you must provide at least 1. Sending an empty array while overriding strength parameters tends to produce low-quality output — omit the field entirely instead.
Providing only lyrics or tags (without a prompt) is not supported. However, you can pass an empty string as the prompt to leave the style/lyrics entirely up to the AI.
For instrumental songs, set instrumental to true and don't pass any lyrics. In the instrumental case, only the tags or prompt can be set (where the prompt will only be used to generate tags).

Other Parameters (v2 & v3)

prompt_strength - Greater values adhere more to the prompt but sound less natural. Defaults are tuned — leave unset unless you are actively iterating. On v3, valid range is 1.0 – 4.0 (default 1.0) and exactly one of prompt_strength and style_scale must be greater than 1.0.
webhook_url - This URL will receive POST requests while the song is being generated with status updates.
align_lyrics - When true, performs lyrics alignment after generation completes. This produces word-level timing data that syncs lyrics to the audio. For v2, requires num_songs=1. See the Lyrics Alignment section for more details.

v3-only Parameters

style_scale - Greater values adhere more to the style implied by the prompt/tags but sound less natural. Default is 2.3. Valid range is 1.0 – 12.0. Exactly one of prompt_strength and style_scale must be greater than 1.0 — by default style_scale is 2.3 and prompt_strength is 1.0, so if you raise prompt_strength above 1.0 you must drop style_scale to 1.0.
negative_tags - Array of style tags the model should avoid. Useful for steering away from undesired genres or instruments. Uses the same tag vocabulary as tags.
length_range - Optional [min_seconds, max_seconds] hint for the target song length. Both values must be multiples of 30; min in 0–270, max in 30–300. A single v3 generation is capped at 4 minutes 45 seconds (the model's context window), so a max of 300 is only there because 4:45 rounds up to the next multiple of 30. It will not produce a 5 minute song.
enable_streaming - When true, the generation can be streamed in real time via the streaming endpoint while it's still being created.
stream_format - The audio format used by the streaming endpoint. Either ogg (default) or mp3.

Output Audio Formats

The default output format is variable bitrate opus in an ogg container (a .ogg file). You can change this by setting the output_format option.
Supported formats: mp3, flac, wav, ogg (opus), m4a (aac)
Additionally, for mp3 and m4a, you can set a bitrate with the output_bit_rate option. This can be left null to use reasonable defaults. Supported bit rates for mp3 and m4a (in kbps): 128, 192, 256, 320.

Statuses

You can view the current status of your generation request using the GET /generations/{task_id} endpoint described below. Alternatively, you can specify a webhook_url to get updates in real-time. Either way, you will recieve the following status updates in order:

RECEIVED - Sent immediately after we parse your request.
TRANSCRIBE_TASK_STARTED (inpaint/extend/reference only)
TRANSCRIBE_STAGE_1 (inpaint/extend/reference only)
TRANSCRIBE_STAGE_2 (inpaint/extend/reference only)
TRANSCRIBE_STAGE_3 (inpaint/extend/reference only)
TRANSCRIBE_DONE (inpaint/extend/reference only)
PROMPT - We are converting your prompt to tags and/or lyrics.
TASK_SENT - Everything is ready and we've sent your task to our GPU cluster.
GENERATE_TASK_STARTED - A GPU worker has been assigned to your task and has started working on it.
LOADING_SOURCE (inpaint/extend only) - We are fetching your source song to inpaint or extend.
BEGINNING_GENERATION - Sent right before your song starts generating.
GENERATING - The main event! Your song is being generated.
GENERATING_STREAMING_READY - v3 only. Indicates that you can connect to the streaming endpoint to start listening to the song while it generates.
DECOMPRESSING - Decompressing your song from our latent space.
SAVING - Uploading your song to our CDN.
SUCCESS - Everything worked! Your song URL(s) will be posted in the body of this request at the key song_paths, or you can fetch them using the GET /generations/{task_id} endpoint. Note: These URLs expire and are not permanent. Song URLs are unlisted rather than access-controlled — anyone with the URL can fetch the file, so treat URLs with the same care as the audio itself. See Data Fetching Endpoints for more information.
FAILURE - Something went wrong. Don't worry, no credits were deducted. Please try again or contact us :)

v3

v3 Preview

v3 is currently in beta as v3-preview. During the preview period, results may occasionally be lower quality than v2, and parameter behavior may change as we refine the model. For best results, we recommend the default values.

Best practice: just send a prompt

The simplest and highest-quality way to call v3 is to send only prompt and let the model infer everything else. Only supply tags if you have a specific style to enforce — and if you do, provide at least 1 tag (recommended 3 minimum) (the API will reject an empty array). The most common source of poor v3 output we see is users sending an empty tags array — omit the field entirely instead.

POST

/generations/v3

Generate a new song using our v3 model. V3 produces variable-length songs (typically 2-4 minutes, up to a maximum of 4 minutes 45 seconds per generation) with superior audio quality. See the parameter details at the top of these docs for more information.

You can start listening to a v3 song in under 20 seconds thanks to streaming. To enable streaming, set enable_streaming to true in your request. See the Streaming section for more information. Use the stream_format parameter to control the audio format of the stream (ogg or mp3).

Request Body

json

{
  "prompt": "string (optional)",
  "tags": "array[string] (optional, min 1 if provided)",
  "lyrics": "string (optional)",
  "instrumental": "boolean (default: false)",
  "prompt_strength": "float (default: 1.0, range: 1.0 - 4.0; exactly one of prompt_strength and style_scale must be > 1.0)",
  "style_scale": "float (default: 2.3, range: 1.0 - 12.0; exactly one of prompt_strength and style_scale must be > 1.0)",
  "negative_tags": "array[string] (optional, tags the model should avoid)",
  "length_range": "array[integer, integer] (optional, [min_seconds, max_seconds]; both multiples of 30, min in 0-270, max in 30-300; output is capped at 285s regardless)",
  "webhook_url": "string (optional)",
  "output_format": "string (default: ogg)",
  "output_bit_rate": "integer (optional)",
  "enable_streaming": "boolean (default: false)",
  "stream_format": "string (default: ogg, options: 'ogg' | 'mp3')",
  "align_lyrics": "boolean (default: false)"
}

Code Samples

python

import requests

url = "https://api.treblo.com/v1/generations/v3"
headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}
# Just send a prompt — let the model infer tags and tune strength.
payload = {
    "prompt": "An upbeat rock song with heavy guitar riffs"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

json

{
  "task_id": "string"
}

POST

/generations/v3/extend

Extend an existing song with the v3 model.

Provide the song you want to extend in one of three ways: audio_url (a publicly available URL), audio_upload_id (returned by POST /uploads; see the "Python (upload)" example below), or audio_base64 (the file bytes as a base64 string, limited to 40MB, not recommended).
context_seconds controls how many seconds of the parent song are fed to the model as context when generating the extension. Must be greater than 0 and at most 284. The context and the new audio share the model's 4 minute 45 second window, so larger values give the model more continuity with the original at the cost of less new audio per call.
crop_duration trims that many seconds off the end of the parent song before the extension starts. Useful for cutting an unwanted outro before continuing the song.

Note

If you want to extend a generation you created with Treblo, please set the audio_url to the path of the audio file on our CDN (instead of a version you downloaded, for instance). This will prevent quality degradation over time because, internally, we will reuse our latent representation of the song instead of re-encoding the audio.

Request Body

json

{
  "prompt": "string (optional)",
  "tags": "array[string] (optional, min 1 if provided)",
  "lyrics": "string (optional)",
  "instrumental": "boolean (default: false)",
  "prompt_strength": "float (default: 1.0, range: 1.0 - 4.0; exactly one of prompt_strength and style_scale must be > 1.0)",
  "style_scale": "float (default: 2.3, range: 1.0 - 12.0; exactly one of prompt_strength and style_scale must be > 1.0)",
  "negative_tags": "array[string] (optional, tags the model should avoid)",
  "length_range": "array[integer, integer] (optional, [min_seconds, max_seconds]; both multiples of 30, min in 0-270, max in 30-300; output is capped at 285s regardless)",
  "webhook_url": "string (optional)",
  "output_format": "string (default: ogg)",
  "output_bit_rate": "integer (optional)",
  "enable_streaming": "boolean (default: false)",
  "stream_format": "string (default: ogg, options: 'ogg' | 'mp3')",
  "align_lyrics": "boolean (default: false)",
  "audio_url": "string (URL)",
  "audio_upload_id": "string (UUID from POST /uploads)",
  "audio_base64": "string (base64)",
  "context_seconds": "float (range: > 0, <= 284)",
  "crop_duration": "float (default: 0.0)"
}

python

import requests

url = "https://api.treblo.com/v1/generations/v3/extend"
headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "audio_url": "https://cdn.treblo.com/pubapi/generations3/audio_a598194b-d464-474c-b1e6-1c99f8f8e457_0.ogg",
    "tags": ["rock", "energetic"],
    "prompt": "Write another verse for my song",
    "context_seconds": 30
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

json

{
  "task_id": "string"
}

POST

/generations/v3/reference

Generate a new song inspired by a reference song. You can use this to reimagine your songs in a new style, create covers/remixes, and change genres.

Provide the reference song in one of three ways: audio_url (a publicly available URL), audio_upload_id (returned by POST /uploads; see the "Python (upload)" example below), or audio_base64 (the file bytes as a base64 string, limited to 40MB, not recommended).
reference_crop_start and reference_crop_end select the window of the reference, in seconds, that the model listens to. Omit both to use the first 90 seconds, or the whole clip if it is shorter. If you set them, set both: the window must be between 12 and 165 seconds long and lie inside the audio.
reference_scale controls how strongly the output follows the reference. 1.0 is neutral; higher values (up to 5.0) track the reference more closely at the cost of variety.
If you omit lyrics, we transcribe the reference and write new lyrics in its style. Use prompt to steer the topic, pass lyrics to use specific words, or set instrumental: true for no vocals.
The reference window and the generated song share a budget of 4 minutes 45 seconds, so a 90 second reference leaves up to about 3 minutes 15 seconds for the output. You can use length_range to steer the model's output length within this budget.

Note

If you want to reference a generation you created with Treblo, please set the audio_url to the path of the audio file on our CDN (instead of a version you downloaded, for instance). This will prevent quality degradation over time because, internally, we will reuse our latent representation of the song instead of re-encoding the audio.

Request Body

json

{
  "prompt": "string (optional)",
  "tags": "array[string] (optional, min 1 if provided)",
  "lyrics": "string (optional)",
  "instrumental": "boolean (default: false)",
  "prompt_strength": "float (default: 1.0, range: 1.0 - 4.0; exactly one of prompt_strength and style_scale must be > 1.0)",
  "style_scale": "float (default: 2.3, range: 1.0 - 12.0; exactly one of prompt_strength and style_scale must be > 1.0)",
  "negative_tags": "array[string] (optional, tags the model should avoid)",
  "length_range": "array[integer, integer] (optional, [min_seconds, max_seconds]; both multiples of 30, min in 0-270, max in 30-300; output is capped at 285s regardless)",
  "webhook_url": "string (optional)",
  "output_format": "string (default: ogg)",
  "output_bit_rate": "integer (optional)",
  "enable_streaming": "boolean (default: false)",
  "stream_format": "string (default: ogg, options: 'ogg' | 'mp3')",
  "align_lyrics": "boolean (default: false)",
  "audio_url": "string (URL)",
  "audio_upload_id": "string (UUID from POST /uploads)",
  "audio_base64": "string (base64)",
  "reference_crop_start": "float (optional, seconds; set together with reference_crop_end)",
  "reference_crop_end": "float (optional, seconds; window must be 12 - 165 seconds long)",
  "reference_scale": "float (default: 1.0, range: 1.0 - 5.0)"
}

python

import requests

url = "https://api.treblo.com/v1/generations/v3/reference"
headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "audio_url": "https://cdn.treblo.com/pubapi/generations3/audio_a598194b-d464-474c-b1e6-1c99f8f8e457_0.ogg",
    "prompt": "A song about a road trip, but mimic the chorus of the reference",
    "reference_crop_start": 0,
    "reference_crop_end": 90,
    "reference_scale": 2.0
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

json

{
  "task_id": "string"
}

Uploads

POST

/uploads

Upload an audio file to use as the source for extend, inpaint, and reference requests. This method is recommended over base64 encoding since it avoids the base64 overhead.

Send the file as multipart/form-data in a field named file. Supported formats: mp3, m4a, ogg, flac, wav, amr, aac, aiff. Maximum size is 40MB.
The response contains an audio_upload_id. Pass it as the audio_upload_id field of a generation request instead of audio_url or audio_base64.
One upload can be used by any number of requests while it is available. Uploads expire about 24 hours after they are created. Treat the id as private: anyone who has it can use it until it expires.

python

import requests

url = "https://api.treblo.com/v1/uploads"
headers = {"Authorization": "Bearer your_api_key_here"}

with open("audio.mp3", "rb") as f:
    response = requests.post(url, headers=headers, files={"file": f})

audio_upload_id = response.json()["audio_upload_id"]
print(audio_upload_id)

Response

json

{
  "audio_upload_id": "string (UUID)"
}

Data Fetching Endpoints

Important Details

Songs may be deleted from our severs one week (168 hours) after they were generated. This means the URLs in song_paths may not work after this time. In some circumstances, songs may be accessible after this time, but this is not guaranteed. Make sure to download any songs you want to keep!

GET

/generations/{task_id}

Retrieve the final generated song and all the parameters you used to generate it. The final audio URL is also sent over the webhook_url if you set it.

Code Samples

python

import requests

task_id = "your_task_id"
url = f"https://api.treblo.com/v1/generations/{task_id}"
headers = {
    "Authorization": "Bearer your_api_key_here"
}

response = requests.get(url, headers=headers)
print(response.json())

Response

json

{
  "id": "string (UUID)",
  "created_at": "string (ISO 8601 timestamp)",
  "status": "string",
  "alignment_status": "string | null",
  "model_version": "string (e.g. 'v2.2', 'v3-preview')",
  "song_paths": "array[string] (URLs)",
  "error_message": "string | null",
  "lyrics": "string",
  "prompt": "string | null",
  "prompt_strength": "float",
  "style_scale": "float",
  "tags": "array[string]",
  "v2_params": {
    "balance_strength": "float",
    "seed": "integer",
    "bpm": "'auto' | integer | null"
  },
  "v3_params": {
    "negative_tags": "array[string]",
    "length_range": "array[integer, integer] | null"
  },
  "inpaint_params": {
    "sections": "array[array[float]]",
    "selection_crop": "boolean",
    "audio_url": "string (URL)",
    "lyrics": "string"
  },
  "extend_params": {
    "side": "string",
    "crop_duration": "float",
    "audio_url": "string (URL)",
    "lyrics": "string",
    "duration": "float",
    "start_end_song": "'start' | 'end' | 'both' | null",
    "context_seconds": "float"
  },
  "reference_params": {
    "crop_start": "float | null (null until generation starts)",
    "crop_end": "float | null (null until generation starts)",
    "reference_scale": "float",
    "audio_url": "string (URL)"
  }
}

Field Descriptions

id: Unique identifier for the generation
created_at: Timestamp when the generation was created
status: Current status of the generation
alignment_status: Status of lyrics alignment post-processing (null if alignment was not requested)
model_version: The model version used for generation (e.g. "v2.2", "v3-preview")
song_paths: Array of URLs to the generated audio files
error_message: If the generation state is FAILURE, this may contain helpful information to understand what went wrong.
lyrics: Generated or provided lyrics
prompt: The prompt used for generation (if any)
prompt_strength: Greater values adhere more to the prompt but sound less natural. Defaults are tuned — leave unset unless you are actively iterating.
style_scale: Greater values adhere more to the style implied by the prompt/tags but sound less natural. Default is 2.3. v3 only.
tags: Array of musical style tags
v2_params: Parameters specific to v2 generations (null for v3). Contains:
- balance_strength: Greater means more natural vocals. Lower means sharper instrumentals. We recommend 0.7.
- seed: Random seed used for generation
- bpm: The beats per minute used for generation
v3_params: Parameters specific to v3 generations (null for v2). Contains:
- negative_tags: Tags the model was instructed to avoid
- length_range: The [min_seconds, max_seconds] length hint passed to the model, or null if unset
inpaint_params: Parameters used if this was an inpainting operation
extend_params: Parameters used if this was an extension operation
reference_params: Parameters used if this was a reference (cover) operation

GET

/generations/status/{task_id}

Check the status of a generation task.

Parameters

task_id - The ID of the generation task
include_alignment - Optional query parameter (default: false). When true, returns a JSON object with both the generation status and alignment status. Alignment is an optional post-processing step that syncs lyrics to the audio.

Code Samples

python

import requests

task_id = "your_task_id"
url = f"https://api.treblo.com/v1/generations/status/{task_id}"
headers = {
    "Authorization": "Bearer your_api_key_here"
}

response = requests.get(url, headers=headers)
print(response.json())  # Returns: "GENERATING"

Response

By default, returns a plain string with the generation status:

json

"SUCCESS"

With include_alignment=true, returns a JSON object:

json

{
  "status": "string",
  "alignment_status": "string | null"
}

The alignment_status will be null if alignment was not requested for this generation.

GET

/credits/balance

Check the number of credits you have left.

python

import requests

url = "https://api.treblo.com/v1/credits/balance"
headers = {
  "Authorization": "Bearer your_api_key_here"
}

response = requests.get(url, headers=headers)
print(response.json())

Response

json

{
  "num_credits": "integer",
  "num_credits_payg": "integer"
}

Field Descriptions

num_credits: The number of subscription credits remaining
num_credits_payg: The number of pay-as-you-go credits remaining

Streaming

v3 generations can be streamed in real time as the audio is being generated. This allows you to start playing a song before it has finished generating. Streaming is only available for v3 generations.

Important

You must set enable_streaming to true in your generation request. Streaming is disabled by default. If you did not enable it when creating the generation, the streaming endpoint will not work for that track.
The streaming endpoint is only available while the song is being generated and for a few seconds after generation completes. Once the stream expires, you must use the final audio URL from the song_paths field returned by the GET /generations/{task_id} endpoint.

GET

https://api-stream.treblo.com/stream/{task_id}

Stream audio for a v3 generation as it's being created. The endpoint returns audio chunks as they are produced by the model. If you connect after generation has started, you will receive all previously generated audio immediately, then continue receiving new chunks as they are generated. The URL is known as soon as you have the task id, but it only becomes valid once the task reaches GENERATING_STREAMING_READY (via the status endpoint or your webhook).

Parameters

task_id - The task ID returned when you created the v3 generation

Response

Returns a streaming audio response. Returns opus in an ogg container by default, but can also return mp3 if requested during the generation request. The Content-Type header will be one of:

audio/ogg; codecs="opus" (default)
audio/mpeg (mp3)

Errors

400 Bad Request - The track is not ready for streaming yet. Wait for the generation to reach the GENERATING_STREAMING_READY status before attempting to stream.

Code Samples

markup

<!-- The streaming endpoint can be used directly with an HTML audio element -->
<audio controls autoplay>
  <source src="https://api-stream.treblo.com/stream/your_task_id" type="audio/ogg" />
</audio>

Lyrics Alignment

Lyrics alignment is an optional post-processing step that produces word-level timing data, syncing your lyrics to the generated audio.

Requirements

Alignment only works for non-instrumental songs with lyrics. If the song is instrumental or has no lyrics, alignment will not run (you can still set align_lyrics, it will simply be ignored).
For v2 generations: You must set num_songs=1 when using align_lyrics=true.

Alignment Status Flow

When you set align_lyrics=true in your generation request, the alignment process follows these status updates:

REQUESTED - Alignment has been requested and will run after the generation completes successfully.
TASK_SENT - The generation succeeded and the alignment task has been sent to our workers.
ALIGNING - A worker is actively processing the alignment.
SUCCESS - Alignment completed successfully. The aligned lyrics are now available.
FAILURE - Something went wrong during alignment.

Important

If the main generation fails (status becomes FAILURE), the alignment_status will remain in REQUESTED state because the alignment task never runs. Always check the main status first before checking alignment_status.

If alignment fails, but the generation succeeds, credits will be deducted.

Checking Alignment Status

Use the GET /generations/status/{task_id} endpoint with include_alignment=true to check both the generation and alignment status:

json

{
  "status": "SUCCESS",
  "alignment_status": "ALIGNING"
}

Webhook Updates

If you specified a webhook_url, you will receive webhook updates for alignment status changes. The webhook payload will include an alignment_status field when alignment is in progress or complete.

Legacy (v2)

The v2 endpoints below are kept for existing integrations. New integrations should use the v3 endpoints above. v2 will not receive new features.

v2-only Parameters (deprecated)

balance_strength - Greater means more natural vocals. Lower means sharper instrumentals. We recommend 0.7.
seed - The number used to seed the random number generator. The same tags and lyrics with the same seed will generate the same song.
num_songs - The number of songs to generate. Must be 1 or 2. Generating 2 songs will use 150 credits instead of 100! Also, this value controls the length of the song_paths array returned by the status endpoint. v3 always generates 1 song.

POST

/generations/v2

Generate a new 1 minute 35 second song using our v2 model. See the parameter details at the top of these docs for more information. The parameters below are unique to this endpoint.

bpm - The beats per minute of the song. This can be set to an integer or the literal string "auto" to pick a suitable bpm based on the tags. Set bpm to null to not condition the model on bpm information.

Request Body

json

{
  "tags": "array[string] (optional)",
  "lyrics": "string (optional)",
  "prompt": "string (optional)",
  "instrumental": "boolean (default: false)",
  "prompt_strength": "float",
  "balance_strength": "float (default: 0.7)",
  "seed": "integer (optional)",
  "webhook_url": "string (optional)",
  "num_songs": "integer (default: 1)",
  "output_format": "string (default: ogg)",
  "output_bit_rate": "integer (optional)",
  "align_lyrics": "boolean (default: false)",
  "bpm": "'auto' or integer (optional)"
}

Code Samples

python

import requests

url = "https://api.treblo.com/v1/generations/v2"
headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "tags": ["rock", "energetic"],
    "prompt": "An upbeat rock song with heavy guitar riffs"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

json

{
  "task_id": "string"
}

POST

/generations/v2/extend

Extend an existing song.

Provide the song you want to extend in one of three ways: audio_url (a publicly available URL), audio_upload_id (returned by POST /uploads; see the "Python (upload)" example below), or audio_base64 (the file bytes as a base64 string, limited to 40MB, not recommended).
You can extend from the start or end of the song by setting the side to "left" or "right," respectively. extend_duration determines how much new audio to generate. This must be between 0 and 85.0 seconds.
Finally, the crop_duration can be used to crop the end (or start, depending on the value of side) of the original audio before extending.

Note

Request Body

json

{
  "tags": "array[string] (optional)",
  "lyrics": "string (optional)",
  "prompt": "string (optional)",
  "instrumental": "boolean (default: false)",
  "prompt_strength": "float",
  "balance_strength": "float (default: 0.7)",
  "seed": "integer (optional)",
  "webhook_url": "string (optional)",
  "num_songs": "integer (default: 1)",
  "output_format": "string (default: ogg)",
  "output_bit_rate": "integer (optional)",
  "align_lyrics": "boolean (default: false)",
  "audio_url": "string (URL)",
  "audio_upload_id": "string (UUID from POST /uploads)",
  "audio_base64": "string (base64)",
  "side": "string (left | right)",
  "extend_duration": "float (optional)",
  "crop_duration": "float (default: 0.0)"
}

python

import requests

url = "https://api.treblo.com/v1/generations/v2/extend"
headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "audio_url": "https://cdn.treblo.com/generations2/audio_a598194b-d464-474c-b1e6-1c99f8f8e457_0.ogg",
    "tags": ["rock", "energetic"],
    "prompt": "Write another verse for my song",
    "side": "right",
    "extend_duration": 45.0
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

json

{
  "task_id": "string"
}

POST

/generations/v2/inpaint

Replace sections of an existing audio with newly generated content.

Provide the song you want to inpaint in one of three ways: audio_url (a publicly available URL), audio_upload_id (returned by POST /uploads; see the "Python (upload)" example below), or audio_base64 (the file bytes as a base64 string, limited to 40MB, not recommended).
sections represents the sections you want to replace. Currently, it is only possible to inpaint one section. Thus, the outer list must be of length 1. The inner list must have two floats representing the start and end timestamps (in seconds) of the section to replace.
selection_crop will crop the final output to only contain the inpainted section.

Note

If you want to inpaint a generation you created with Treblo, please set the audio_url to the path of the audio file on our CDN (instead of a version you downloaded, for instance). This will prevent quality degradation over time because, internally, we will reuse our latent representation of the song instead of re-encoding the audio.

Request Body

json

{
  "tags": "array[string] (optional)",
  "lyrics": "string",
  "prompt": "string (optional)",
  "instrumental": "boolean (default: false)",
  "prompt_strength": "float",
  "balance_strength": "float (default: 0.7)",
  "seed": "integer (optional)",
  "webhook_url": "string (optional)",
  "num_songs": "integer (default: 1)",
  "output_format": "string (default: ogg)",
  "output_bit_rate": "integer (optional)",
  "align_lyrics": "boolean (default: false)",
  "audio_url": "string (URL)",
  "audio_upload_id": "string (UUID from POST /uploads)",
  "audio_base64": "string (base64)",
  "sections": "array[array[float]]",
  "selection_crop": "boolean (default: false)"
}

python

import requests

url = "https://api.treblo.com/v1/generations/v2/inpaint"
headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "audio_url": "https://cdn.treblo.com/generations2/audio_a598194b-d464-474c-b1e6-1c99f8f8e457_0.ogg",
    "tags": ["rock", "energetic"],
    "sections": [[0.0, 30.0]],
    "lyrics": "New lyrics for the sections"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

json

{
  "task_id": "string"
}