curl --request PUT \
--url https://api.soundpiece.co/v1/create.new_song \
--header 'Content-Type: application/json' \
--data '
{
"idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"lyrics": "<string>",
"reference": {
"url": "<string>"
},
"callback_url": "<string>",
"n_variations": 1
}
'import requests
url = "https://api.soundpiece.co/v1/create.new_song"
payload = {
"idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"lyrics": "<string>",
"reference": { "url": "<string>" },
"callback_url": "<string>",
"n_variations": 1
}
headers = {"Content-Type": "application/json"}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
idempotency_key: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
lyrics: '<string>',
reference: {url: '<string>'},
callback_url: '<string>',
n_variations: 1
})
};
fetch('https://api.soundpiece.co/v1/create.new_song', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.soundpiece.co/v1/create.new_song",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'idempotency_key' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'lyrics' => '<string>',
'reference' => [
'url' => '<string>'
],
'callback_url' => '<string>',
'n_variations' => 1
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.soundpiece.co/v1/create.new_song"
payload := strings.NewReader("{\n \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"lyrics\": \"<string>\",\n \"reference\": {\n \"url\": \"<string>\"\n },\n \"callback_url\": \"<string>\",\n \"n_variations\": 1\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.soundpiece.co/v1/create.new_song")
.header("Content-Type", "application/json")
.body("{\n \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"lyrics\": \"<string>\",\n \"reference\": {\n \"url\": \"<string>\"\n },\n \"callback_url\": \"<string>\",\n \"n_variations\": 1\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.soundpiece.co/v1/create.new_song")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"lyrics\": \"<string>\",\n \"reference\": {\n \"url\": \"<string>\"\n },\n \"callback_url\": \"<string>\",\n \"n_variations\": 1\n}"
response = http.request(request)
puts response.read_body{
"song": {
"id": "<string>",
"status": "processing",
"created_at": "2023-11-07T05:31:56Z",
"idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"lyrics": "<string>",
"n_variations": 2,
"prompt": "<string>",
"outputs": [
{
"url": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"duration": 123
}
],
"error": {
"code": "internal_error",
"message": "<string>"
}
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}create.new_song
Submit a song generation request.
Returns immediately with status: processing. Use the matching GET to
poll for completion, or supply a callback_url to receive a webhook.
Songs are generated from lyrics plus either a text prompt or a reference
track URL. Set n_variations (1-3) for how many variations to produce —
each appears as a separate entry in outputs when the operation is ready.
Credits cost: 3 per variation (so n_variations: 2 costs 6).
Insufficient credits returns 402 — see errors.
curl --request PUT \
--url https://api.soundpiece.co/v1/create.new_song \
--header 'Content-Type: application/json' \
--data '
{
"idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"lyrics": "<string>",
"reference": {
"url": "<string>"
},
"callback_url": "<string>",
"n_variations": 1
}
'import requests
url = "https://api.soundpiece.co/v1/create.new_song"
payload = {
"idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"lyrics": "<string>",
"reference": { "url": "<string>" },
"callback_url": "<string>",
"n_variations": 1
}
headers = {"Content-Type": "application/json"}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
idempotency_key: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
lyrics: '<string>',
reference: {url: '<string>'},
callback_url: '<string>',
n_variations: 1
})
};
fetch('https://api.soundpiece.co/v1/create.new_song', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.soundpiece.co/v1/create.new_song",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'idempotency_key' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'lyrics' => '<string>',
'reference' => [
'url' => '<string>'
],
'callback_url' => '<string>',
'n_variations' => 1
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.soundpiece.co/v1/create.new_song"
payload := strings.NewReader("{\n \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"lyrics\": \"<string>\",\n \"reference\": {\n \"url\": \"<string>\"\n },\n \"callback_url\": \"<string>\",\n \"n_variations\": 1\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.soundpiece.co/v1/create.new_song")
.header("Content-Type", "application/json")
.body("{\n \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"lyrics\": \"<string>\",\n \"reference\": {\n \"url\": \"<string>\"\n },\n \"callback_url\": \"<string>\",\n \"n_variations\": 1\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.soundpiece.co/v1/create.new_song")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"lyrics\": \"<string>\",\n \"reference\": {\n \"url\": \"<string>\"\n },\n \"callback_url\": \"<string>\",\n \"n_variations\": 1\n}"
response = http.request(request)
puts response.read_body{
"song": {
"id": "<string>",
"status": "processing",
"created_at": "2023-11-07T05:31:56Z",
"idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"lyrics": "<string>",
"n_variations": 2,
"prompt": "<string>",
"outputs": [
{
"url": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"duration": 123
}
],
"error": {
"code": "internal_error",
"message": "<string>"
}
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Body
- CreateNewSongReferenceRequest
- CreateNewSongPromptRequest
A unique UUID you choose. Send the same key to retry safely; we'll return the original response without doing the work again.
Song lyrics. Use [Verse], [Chorus], [Bridge], [Intro], [Outro], [Instrumental] section markers on their own line to structure the song. Each subsequent line within a section is a separate vocal line.
Example:
[Verse]
This is a demo song, don't get too excited
Wrote it in me lounge while slightly half-sighted
[Chorus]
It's only a demo, keep your hopes low
Recorded it once, then decided "that'll go"
1 - 3000An audio source to use as a reference for generation.
Show child attributes
Show child attributes
Optional HTTPS URL we'll POST the final response to when the operation reaches ready or failed. Polling remains the canonical source of truth; webhooks are a best-effort latency optimisation.
1 - 2048How many output variations to produce (1-3).
1 <= x <= 3Response
Successful Response
Show child attributes
Show child attributes
