# A complete program that also waits for the result and downloads it:
# https://docs.soundpiece.co/guides/create/new_sample
# One key per job: keep it, and send the same key if you retry.
IDEMPOTENCY_KEY=$(uuidgen)
curl --request PUT \
--url https://api.soundpiece.co/v1/create.new_sample \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"idempotency_key": "$IDEMPOTENCY_KEY",
"prompt": "punchy kick drum, deep, dry",
"duration": 4.0
}
EOF# A complete program that also waits for the result and downloads it:
# https://docs.soundpiece.co/guides/create/new_sample
import uuid
import requests
url = "https://api.soundpiece.co/v1/create.new_sample"
# One key per job: keep it, and send the same key if you retry.
idempotency_key = str(uuid.uuid4())
payload = {
"idempotency_key": idempotency_key,
"prompt": "punchy kick drum, deep, dry",
"duration": 4.0,
}
headers = {"Authorization": "Bearer <token>"}
response = requests.put(url, json=payload, headers=headers, timeout=30)
print(response.json())// A complete program that also waits for the result and downloads it:
// https://docs.soundpiece.co/guides/create/new_sample
import { randomUUID } from "node:crypto";
// One key per job: keep it, and send the same key if you retry.
const idempotencyKey = randomUUID();
const response = await fetch("https://api.soundpiece.co/v1/create.new_sample", {
method: "PUT",
headers: {Authorization: "Bearer <token>", "Content-Type": "application/json"},
body: JSON.stringify({
idempotency_key: idempotencyKey,
prompt: "punchy kick drum, deep, dry",
duration: 4.0,
}),
});
console.log(await response.json());{
"sample": {
"id": "op_01m3vcs7e0f8rsq32d5sqhmetw",
"status": "processing",
"created_at": "2026-10-01T09:30:00Z",
"idempotency_key": "3f2b8c1e-9d4a-4e7b-b6c5-1a2d3e4f5a6b",
"prompt": "rock, guitar, energetic, no drums",
"duration": 8,
"loopable": true,
"output": null,
"error": null
}
}create.new_sample (submit)
Submit a sample generation request.
Returns immediately with status: processing. Use the matching GET to
poll for completion, or supply a callback_url to receive a webhook.
Samples are short audio clips generated from a text prompt at the
requested duration. Set loopable: true to produce a clip designed to
repeat seamlessly. A prompt rejected by our content policy returns the
operation as failed with tos_violation.
Credits cost: 3 per request. Insufficient credits returns 402 —
see errors.
# A complete program that also waits for the result and downloads it:
# https://docs.soundpiece.co/guides/create/new_sample
# One key per job: keep it, and send the same key if you retry.
IDEMPOTENCY_KEY=$(uuidgen)
curl --request PUT \
--url https://api.soundpiece.co/v1/create.new_sample \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"idempotency_key": "$IDEMPOTENCY_KEY",
"prompt": "punchy kick drum, deep, dry",
"duration": 4.0
}
EOF# A complete program that also waits for the result and downloads it:
# https://docs.soundpiece.co/guides/create/new_sample
import uuid
import requests
url = "https://api.soundpiece.co/v1/create.new_sample"
# One key per job: keep it, and send the same key if you retry.
idempotency_key = str(uuid.uuid4())
payload = {
"idempotency_key": idempotency_key,
"prompt": "punchy kick drum, deep, dry",
"duration": 4.0,
}
headers = {"Authorization": "Bearer <token>"}
response = requests.put(url, json=payload, headers=headers, timeout=30)
print(response.json())// A complete program that also waits for the result and downloads it:
// https://docs.soundpiece.co/guides/create/new_sample
import { randomUUID } from "node:crypto";
// One key per job: keep it, and send the same key if you retry.
const idempotencyKey = randomUUID();
const response = await fetch("https://api.soundpiece.co/v1/create.new_sample", {
method: "PUT",
headers: {Authorization: "Bearer <token>", "Content-Type": "application/json"},
body: JSON.stringify({
idempotency_key: idempotencyKey,
prompt: "punchy kick drum, deep, dry",
duration: 4.0,
}),
});
console.log(await response.json());{
"sample": {
"id": "op_01m3vcs7e0f8rsq32d5sqhmetw",
"status": "processing",
"created_at": "2026-10-01T09:30:00Z",
"idempotency_key": "3f2b8c1e-9d4a-4e7b-b6c5-1a2d3e4f5a6b",
"prompt": "rock, guitar, energetic, no drums",
"duration": 8,
"loopable": true,
"output": null,
"error": null
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
A unique UUID you choose. Send the same key to retry safely; we'll return the original response without doing the work again.
"3f2b8c1e-9d4a-4e7b-b6c5-1a2d3e4f5a6b"
Free-text description of the audio to generate. Mix tags, a description of the desired mood and instrumentation, and a scene — use commas to separate tags. Examples: rock song, energetic, male vocal (song), synthwave, melancholic, mid-tempo (instrumental), rock, guitar, energetic, no drums (sample), someone typing on a keyboard (effect).
1 - 1024Duration in seconds.
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 - 2048"https://example.com/webhooks/soundpiece"
Whether the sample should be designed to loop seamlessly.
Response
Successful Response
Show child attributes
Show child attributes
