API di provenienza dei contenuti (Beta)

L’audio generato da ElevenLabs contiene una filigrana non udibile incorporata direttamente nei campioni audio. L’endpoint di provenienza dei contenuti, POST /v1/content-provenance/watermark, legge un file che carichi e ti comunica se ne rileva una.

Quando la filigrana corrisponde a un record di generazione, la risposta indica il prodotto e il modello che hanno generato l’audio, quando è stato generato e un ID per quella generazione. Non include mai il prompt, l’account o l’utente dietro la generazione.

Cosa indica la filigrana

Un controllo completato restituisce due campi: is_detected e details.

is_detected è true quando il decoder ha riconosciuto una filigrana di ElevenLabs nel file, e false quando non l’ha riconosciuta.

details viene compilato solo quando è possibile recuperare dalla filigrana i dettagli della generazione, cosa che potrebbe non essere possibile per audio brevi o modificati in modo significativo. Include quindi product, model, generated_at e unique_id. Ciascuno di questi quattro campi può essere null. Se non corrisponde alcun record o non viene trovata alcuna filigrana, details è null.

Puoi anche inviare version per scegliere quale decoder legge il file. Omettilo oppure invia latest per usare il decoder più recente. Al momento è supportato solo latest.

Verifica un file

Carica l’audio come form multipart con il nome del campo file e imposta il media type della parte, ad esempio audio/mpeg. La tua chiave API deve disporre dell’autorizzazione per le filigrane. I token di accesso OAuth non sono accettati.

curl -X POST https://api.elevenlabs.io/v1/content-provenance/watermark \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -F "file=@./example.mp3;type=audio/mpeg"

version è facoltativo. Per inviarlo esplicitamente:

curl -X POST https://api.elevenlabs.io/v1/content-provenance/watermark \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -F "file=@./example.mp3;type=audio/mpeg" \
  -F "version=latest"

Un file che contiene una filigrana restituisce qualcosa di simile:

{
  "is_detected": true,
  "details": {
    "product": "Music",
    "model": "Eleven Music v2",
    "generated_at": "2026-07-27T18:34:12+00:00",
    "unique_id": "row-123"
  }
}

Limiti

File accettati. Qualsiasi tipo audio/* che il decoder può leggere, inclusi MP3, WAV, FLAC, AAC e Ogg. Puoi anche omettere il media type o inviare application/octet-stream. Un’immagine o qualsiasi altro tipo non audio restituisce 400 con lo stato invalid_file_type.

Dimensioni e durata. Ogni file può avere una dimensione massima di 50 MB e una durata compresa tra 0,5 secondi e 5 minuti dopo la decodifica. Invia un file per richiesta.

Limite di frequenza. Ogni utente della chiave API può inviare 25 controlli ogni 24 ore. Le richieste che superano questo limite restituiscono 429. Se hai bisogno di un limite più alto, contattaci.

Gestione degli errori

Vale la pena riprovare più tardi in caso di 429. Un 400 o 422 indica che la richiesta stessa deve essere modificata, ad esempio perché contiene un file non audio o una version diversa da latest.

Utilizzare il risultato

L’endpoint legge la filigrana già presente nel file, niente di più. La risposta non contiene né il prompt né l’account, quindi per qualsiasi decisione che dipenda dalla provenienza dell’audio, mantieni una persona nel processo.