Documentazione API

Introduzione

L’API fa esattamente quello che fa il sito. Invii un’occasione, il nome della persona a cui è dedicata la canzone e qualche dettaglio concreto. Ne nasce prima un testo completo, poi una registrazione prodotta con voce, arrangiamento e mix. L’intero processo richiede di solito dai cinque ai dieci minuti.

Tutte le richieste vanno a https://api.tuacanzone.it/v1. L’API parla soltanto HTTPS, accetta JSON e risponde in JSON. Non esiste un SDK obbligatorio: basta un linguaggio qualsiasi che sappia fare HTTP. Gli esempi di questa pagina usano curl, Python e Node, perché sono i tre casi più frequenti.

Ogni dominio ha la propria base API e il proprio prezzo nella valuta locale. Una chiave vale per il dominio per cui è stata emessa. Chi serve più mercati riceve più chiavi oppure una chiave abilitata su più domini.

Accesso

Non esiste volutamente una registrazione automatica. Rilasciamo le chiavi a mano, perché dietro ogni canzone ci sono costi di produzione reali e vogliamo sapere a cosa serve l’integrazione. In pratica si tratta di una breve mail e di un giorno lavorativo.

Scrivi a songs@maxkuch.com indicando quattro cose:

• Che cosa vuoi costruire, in due o tre frasi.
• Il volume approssimativo al mese.
• In quali lingue devono essere cantate le canzoni.
• Se puoi ricevere webhook o preferisci fare polling.

Riceverai due chiavi: una di test con il prefisso sk_test_, gratuita, che restituisce registrazioni dimostrative fisse, e una live con il prefisso sk_live_. Entrambe funzionano subito, senza abilitare singoli endpoint.

Autenticazione

Ogni richiesta porta la chiave nell’header Authorization come bearer token. Le richieste senza header valido ricevono 401 e il tipo di errore authentication_error.

curl https://api.tuacanzone.it/v1/songs \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "occasion": "birthday",
    "recipient_name": "Anna",
    "relationship": "sister",
    "language": "it",
    "mood": "happy",
    "style": "pop",
    "voice": "female",
    "details": "Climbs every weekend, always ten minutes late, calls everyone chef.",
    "callback_url": "https://example.com/hooks/songs"
  }' 

Tratta la chiave come una password: solo lato server, mai nel codice frontend, mai in un repository pubblico. Se una chiave si perde, scrivici: la blocchiamo subito e ne emettiamo una nuova. Un account può avere più chiavi attive, così la sostituzione avviene senza interruzioni.

Chiavi di test e live condividono gli stessi endpoint. Se una richiesta è avvenuta in modalità test lo dice il campo livemode di ogni oggetto.

Avvio rapido

Creare una canzone è una sola chiamata. La risposta arriva subito e contiene un id con lo stato queued. Tutto il resto avviene in background.

import os, time, requests

API = "https://api.tuacanzone.it/v1"
HEAD = {"Authorization": "Bearer " + os.environ["SONG_API_KEY"]}

song = requests.post(API + "/songs", headers=HEAD, json={
    "occasion": "wedding",
    "recipient_name": "Lea and Tim",
    "relationship": "friends",
    "language": "it",
    "mood": "romantic",
    "details": "Met at a bike repair shop, dog named Miso, both terrible dancers.",
}).json()

while song["status"] not in ("preview_ready", "complete", "failed"):
    time.sleep(5)
    song = requests.get(API + "/songs/" + song["id"], headers=HEAD).json()

print(song["lyrics"])
print(song["preview_url"])

Per semplicità l’esempio fa polling ogni cinque secondi. In produzione i webhook sono la strada migliore, perché risparmiano sia la connessione aperta sia l’attesa. Entrambi sono supportati, i webhook sono descritti più avanti.

Il campo decisivo è details. Lì vanno le cose concrete sulla persona: il soprannome, la mania, la vacanza andata storta. Frasi generiche come "è una persona affettuosa" producono versi generici. Bastano tre o cinque dettagli concreti: sono la differenza fra una canzone carina e una davvero personale.

Gli endpoint in breve

Creare una canzone

POST /v1/songs riceve il briefing e parte subito. Solo tre campi sono obbligatori, tutti gli altri hanno valori predefiniti sensati o vengono scelti in base all’occasione.

const res = await fetch("https://api.tuacanzone.it/v1/songs", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SONG_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    occasion: "anniversary",
    recipient_name: "Mara",
    relationship: "partner",
    language: "it",
    mood: "warm",
    details: "Ten years, three apartments, one very loud coffee machine.",
    callback_url: "https://example.com/hooks/songs",
    metadata: { order_id: "A-10423" },
  }),
});

const song = await res.json();
console.log(song.id, song.status);

L’oggetto canzone

Ogni endpoint che restituisce una singola canzone restituisce lo stesso oggetto. I campi non ancora definiti sono null e si riempiono durante la produzione.

{
  "id": "sng_3n8Kd2ZpQv",
  "object": "song",
  "status": "queued",
  "created_at": "2026-09-16T09:41:02Z",
  "occasion": "birthday",
  "recipient_name": "Anna",
  "relationship": "sister",
  "language": "it",
  "mood": "happy",
  "style": "pop",
  "voice": "female",
  "lyrics": null,
  "preview_url": null,
  "audio_url": null,
  "duration_seconds": null,
  "paid": false,
  "price": { "amount": 2999, "currency": "EUR" },
  "metadata": {},
  "livemode": true
}

{
  "id": "sng_3n8Kd2ZpQv",
  "object": "song",
  "status": "complete",
  "created_at": "2026-09-16T09:41:02Z",
  "completed_at": "2026-09-16T09:47:35Z",
  "lyrics": "[Verse 1]\nAnna, six in the morning, chalk on your hands ...",
  "preview_url": "https://cdn.tuacanzone.it/preview/sng_3n8Kd2ZpQv.mp3",
  "audio_url": "https://cdn.tuacanzone.it/full/sng_3n8Kd2ZpQv.mp3?expires=1789412855&sig=...",
  "duration_seconds": 184,
  "paid": true,
  "price": { "amount": 2999, "currency": "EUR" },
  "metadata": { "order_id": "A-10423" },
  "livemode": true
}

Valori di stato

Una canzone attraversa gli stati in quest’ordine. Non torna mai indietro, e complete, failed e cancelled sono stati finali.

Un singolo tentativo di produzione fallito non porta subito a failed. Internamente riproviamo più volte e ci arrendiamo solo quando falliscono tutti i tentativi. Per questo failed è raro e significa davvero: questa canzone non arriverà.

Recuperare ed elencare

GET /v1/songs/{id} restituisce lo stato attuale di una canzone. L’endpoint è leggero e può essere interrogato ogni secondo, purché si rispetti il limite di frequenza.

curl -G https://api.tuacanzone.it/v1/songs \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -d status=complete \
  -d limit=20 \
  -d starting_after=sng_3n8Kd2ZpQv

Gli elenchi sono basati su cursore. Ricevi al massimo limit voci, 20 di default e 100 al massimo, dalla più recente. Se has_more è vero, passi next_cursor come starting_after nella chiamata successiva. Puoi filtrare per status, occasion, language, paid oltre a created_after e created_before.

{
  "object": "list",
  "data": [
    { "id": "sng_9Wq1LmT4bR", "status": "complete", "recipient_name": "Jonas", "...": "..." },
    { "id": "sng_3n8Kd2ZpQv", "status": "complete", "recipient_name": "Anna",  "...": "..." }
  ],
  "has_more": true,
  "next_cursor": "sng_3n8Kd2ZpQv"
}

Testo e audio

Il testo è gratuito e completo, non un estratto. GET /v1/songs/{id}/lyrics lo restituisce come text/plain, con le marcature di strofa e ritornello. Lo stesso testo si trova nel campo lyrics dell’oggetto canzone.

Per l’audio ci sono due livelli. L’anteprima è costituita dai primi 45 secondi della registrazione finita, non da una demo separata: stessa voce, stesso arrangiamento, stesso testo. È disponibile senza pagamento e lo resta. Il file completo lo fornisce GET /v1/songs/{id}/audio solo dopo lo sblocco.

Entrambi gli indirizzi sono firmati e validi 24 ore. Servono a scaricare, non a collegare in modo permanente. Se ti serve un file più a lungo, scaricalo una volta e conservalo da te. Una nuova chiamata all’endpoint genera in qualsiasi momento un indirizzo fresco.

Il formato è sempre MP3 a 320 kbit/s. Chi ha bisogno di WAV aggiunge ?format=wav, disponibile per gli account con opzione studio.

Rigenerare

Se un risultato non convince, rigenerare non costa nulla. POST /v1/songs/{id}/regenerate crea una nuova versione con lo stesso id e riporta lo stato a queued. La versione precedente resta sotto previous_versions.

curl https://api.tuacanzone.it/v1/songs/sng_3n8Kd2ZpQv/regenerate \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keep_lyrics": false,
    "reason": "voice_not_matching",
    "note": "Please try a lower male voice and a slower tempo."
  }' 

Con keep_lyrics: true il testo resta e si rifà solo la registrazione. È la strada giusta quando il testo funziona e solo la voce o il tempo erano sbagliati. Con false viene riscritto anche il testo.

Il campo note entra direttamente nella rigenerazione, quindi una frase concreta paga. "Voce maschile più profonda, più lenta" funziona, "fallo meglio" no. Tre rigenerazioni per canzone sono gratuite, oltre parlane con noi.

Pagamento e sblocco

Ci sono due modi per sbloccare una canzone, a seconda di chi paga.

Paga il cliente finale

POST /v1/songs/{id}/checkout crea una pagina di pagamento ospitata nella valuta del dominio, con i metodi di pagamento abituali in quel paese. Mandi lì il cliente e ricevi l’evento song.paid quando il pagamento va a buon fine.

curl https://api.tuacanzone.it/v1/songs/sng_3n8Kd2ZpQv/checkout \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "success_url": "https://example.com/thanks?song=sng_3n8Kd2ZpQv",
    "cancel_url": "https://example.com/cart"
  }' 

{
  "object": "checkout_session",
  "song": "sng_3n8Kd2ZpQv",
  "url": "https://pay.tuacanzone.it/c/cs_live_8Hd2Kq...",
  "amount": 2999,
  "currency": "EUR",
  "expires_at": "2026-09-16T11:41:02Z"
}

Paghi tu

Sugli account con fatturazione cumulativa, POST /v1/songs/{id}/unlock sblocca subito la canzone e addebita 29,99 € sull’account. Nessuna deviazione su una pagina di pagamento, comodo con una cassa propria.

curl https://api.tuacanzone.it/v1/songs/sng_3n8Kd2ZpQv/unlock \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -X POST

In entrambi i casi vale lo stesso diritto d’uso: non esclusivo, ma espressamente commerciale. Puoi cedere, vendere e pubblicare la canzone finita nell’ambito della tua offerta.

Valori validi

Gli elenchi di occasione, atmosfera, stile, voce e lingua cambiano ogni tanto. Invece di scriverli nel codice, interroga GET /v1/options e tieni il risultato in cache per qualche ora.

{
  "object": "options",
  "language": "it",
  "occasions": ["birthday", "wedding", "anniversary", "farewell", "funeral",
                "christening", "graduation", "christmas", "declaration", "other"],
  "moods":     ["happy", "warm", "funny", "romantic", "gentle", "epic", "surprise_me"],
  "styles":    ["pop", "rock", "folk", "schlager", "hiphop", "ballad", "country",
                "electronic", "jazz", "childrens", "surprise_me"],
  "voices":    ["female", "male", "duet", "choir", "childrens", "surprise_me"],
  "languages": ["de", "en", "dk", "nl", "it", "se", "fr", "es", "no", "pl", "fi", "is", "jp"]
}

Ognuno di questi valori può anche essere omesso. Il valore surprise_me non è un segnaposto ma un’istruzione vera: in quel caso scegliamo di proposito qualcosa che si adatti all’occasione e ai dettagli.

Webhook

Indica in fase di creazione una callback_url e invieremo lì ogni evento con un POST. È la strada consigliata perché risparmia polling e attesa.

{
  "id": "evt_5Tb7Rn2WqX",
  "object": "event",
  "type": "song.completed",
  "created_at": "2026-09-16T09:47:35Z",
  "data": {
    "object": {
      "id": "sng_3n8Kd2ZpQv",
      "object": "song",
      "status": "complete",
      "audio_url": "https://cdn.tuacanzone.it/full/sng_3n8Kd2ZpQv.mp3?expires=1789412855&sig=...",
      "...": "..."
    }
  }
}

Verificare la firma

Ogni consegna porta un header con marca temporale e HMAC-SHA256 su marca temporale, punto e corpo grezzo. Verificalo prima di fidarti del contenuto e scarta tutto ciò che è più vecchio di cinque minuti.

X-Song-Signature: t=1789412855,v1=7f2c1d9a4b6e8035c1f7a29d4e5b0c8371a6d2f94e8b3c07a15d9e2f6b4c8a01

import hashlib, hmac, os, time
from flask import Flask, request, abort

SECRET = os.environ["SONG_WEBHOOK_SECRET"].encode()
app = Flask(__name__)


@app.post("/hooks/songs")
def hook():
    header = request.headers.get("X-Song-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    timestamp, signature = parts.get("t", ""), parts.get("v1", "")

    if abs(time.time() - int(timestamp or 0)) > 300:
        abort(400)  # older than five minutes, treat as replay

    expected = hmac.new(
        SECRET, (timestamp + "." + request.get_data(as_text=True)).encode(),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        abort(400)

    event = request.get_json()
    if event["type"] == "song.completed":
        store(event["data"]["object"])

    return "", 200

Ripetizioni

Ci aspettiamo una risposta 2xx entro dieci secondi. Se non arriva, riproviamo otto volte nell’arco di 24 ore con intervalli crescenti. Le consegne possono quindi ripetersi e, raramente, arrivare fuori ordine: rendi il tuo endpoint idempotente e fidati di created_at, non dell’ora di arrivo.

Idempotenza

Ogni POST accetta l’header Idempotency-Key con un valore univoco qualsiasi, di solito un UUID. Se la stessa chiave torna entro 24 ore restituiamo la risposta originale invece di creare una seconda canzone.

curl https://api.tuacanzone.it/v1/songs \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -H "Idempotency-Key: 9f1c7c2e-0a3b-4c8d-9e21-5f7a1b6c3d40" \
  -H "Content-Type: application/json" \
  -d '{ "occasion": "birthday", "recipient_name": "Anna", "language": "it", "details": "..." }' 

È esattamente la protezione che serve contro gli errori di rete: se una risposta si perde e il tuo codice ripete la richiesta, nasce comunque una sola canzone. Se invii la stessa chiave con un corpo diverso rispondiamo 409 con il tipo di errore conflict.

Errori

Gli errori arrivano sempre nello stesso formato, con type e code leggibili dalla macchina, un messaggio leggibile e, dove serve, il campo interessato. La request_id va inclusa in ogni richiesta di assistenza, così troviamo la chiamata nei log.

{
  "error": {
    "type": "validation_error",
    "code": "details_too_short",
    "message": "details must contain at least 40 characters so the song has something to work with",
    "param": "details",
    "request_id": "req_2Lm9Xc4Kd1"
  }
}

Con 429 e 5xx riprovare ha senso, meglio con intervalli esponenziali e un po’ di casualità. Con un 4xx diverso da 429 non ne ha: la stessa richiesta fallirà di nuovo.

Limiti

Ogni risposta riporta lo stato attuale negli header, così non devi indovinare.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1789412880
X-Concurrent-Limit: 10
X-Concurrent-Running: 3

Limiti più alti non sono un problema, semplicemente non sono l’impostazione di partenza. Se il volume cresce, scrivici due righe e li alziamo.

Versionamento

La versione principale è nel percorso e resta stabile. Dentro v1 arrivano solo modifiche additive: nuovi campi, nuovi valori negli elenchi, nuovi endpoint. I campi esistenti non spariscono e non cambiano significato.

Per una sicurezza in più puoi fissare una data in un header. Senza header vale sempre il comportamento più recente.

X-Song-Version: 2026-09-01

Il tuo codice dovrebbe ignorare i campi sconosciuti nelle risposte invece di rompersi. È l’unica assunzione che facciamo sui client.

Modalità test

Le chiavi con prefisso sk_test_ passano esattamente dagli stessi endpoint, ma non avviano una produzione reale e non costano nulla. Dopo pochi secondi ricevi un testo dimostrativo fisso e una registrazione dimostrativa, e ogni oggetto porta livemode: false.

Così si provano anche i casi spiacevoli. Alcuni nomi nel campo recipient_name forzano un esito preciso: test_fail porta a failed, test_slow a una produzione di circa dieci minuti, test_ratelimit a una risposta 429. Puoi testare la gestione degli errori senza aspettare un guasto vero.

Anche i webhook funzionano in modalità test, con lo stesso meccanismo di firma e un segreto dedicato.

Diritti e dati

Con lo sblocco ottieni un diritto d’uso non esclusivo ma espressamente commerciale sulla canzone finita. Puoi cederla, venderla, eseguirla in pubblico e integrarla nel tuo prodotto. Non esclusivo significa che manteniamo il diritto di usare noi stessi la registrazione, per esempio come esempio.

Sul diritto d’autore della musica generata da intelligenza artificiale molti ordinamenti non hanno ancora una risposta definitiva. Ti garantiamo l’uso per contratto, ma non possiamo assicurare che sulla registrazione nasca un diritto d’autore autonomo opponibile a terzi. Chi ne dipende faccia verificare la cosa prima.

Conserviamo i dati inseriti e le canzoni finite per 90 giorni, poi vengono cancellati. Per cancellare prima una singola canzone c’è DELETE /v1/songs/{id}. Le informazioni di details le usiamo soltanto per produrre quella canzone e mai per addestrare modelli nostri.

Se ci invii dati dei tuoi clienti, tu sei il titolare del trattamento e noi il responsabile. Un accordo sul trattamento dei dati è disponibile su richiesta.

Assistenza

Domande, limiti più alti, accordo sul trattamento dei dati, casi particolari: songs@maxkuch.com. Per i problemi tecnici indica la request_id della risposta di errore, così troviamo subito la chiamata.

Per le integrazioni tramite agenti di intelligenza artificiale esiste anche un server Model Context Protocol, documentato su /mcp/, che usa le stesse chiavi dell’API REST.