# A complete program that also waits for the result and downloads it:
# https://docs.soundpiece.co/guides/create/new_fx
# 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_fx \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"idempotency_key": "$IDEMPOTENCY_KEY",
"prompt": "someone typing on a keyboard",
"duration": 5.0
}
EOF# A complete program that also waits for the result and downloads it:
# https://docs.soundpiece.co/guides/create/new_fx
import uuid
import requests
url = "https://api.soundpiece.co/v1/create.new_fx"
# 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": "someone typing on a keyboard",
"duration": 5.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_fx
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_fx", {
method: "PUT",
headers: {Authorization: "Bearer <token>", "Content-Type": "application/json"},
body: JSON.stringify({
idempotency_key: idempotencyKey,
prompt: "someone typing on a keyboard",
duration: 5.0,
}),
});
console.log(await response.json());create.new_fx (submit)
Submit an audio effect generation request.
Returns immediately with status: processing. Use the matching GET to
poll for completion, or supply a callback_url to receive a webhook.
Effects are short, single-shot audio elements like risers, impacts,
transitions or foley generated from a text prompt at the requested
duration. 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_fx
# 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_fx \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"idempotency_key": "$IDEMPOTENCY_KEY",
"prompt": "someone typing on a keyboard",
"duration": 5.0
}
EOF# A complete program that also waits for the result and downloads it:
# https://docs.soundpiece.co/guides/create/new_fx
import uuid
import requests
url = "https://api.soundpiece.co/v1/create.new_fx"
# 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": "someone typing on a keyboard",
"duration": 5.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_fx
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_fx", {
method: "PUT",
headers: {Authorization: "Bearer <token>", "Content-Type": "application/json"},
body: JSON.stringify({
idempotency_key: idempotencyKey,
prompt: "someone typing on a keyboard",
duration: 5.0,
}),
});
console.log(await response.json());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 sound effect to generate, up to 450 characters. Describe the sound itself and its character — the source, the action and the setting. Examples: someone typing on a keyboard, a deep cinematic impact with a long metallic tail, rising whoosh transition.
1 - 450Duration 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"
Response
Successful Response
Show child attributes
Show child attributes
