← AudioLayer

API Documentation

REST API per integrare AudioLayer nei tuoi sistemi.

Autenticazione

Tutte le richieste richiedono un header Authorization: Bearer <api_key>. Genera la tua API key dalle impostazioni.

curl -H "Authorization: Bearer al_xxxx" https://audiolayer.it/api/v1/sites

Codici di risposta

200Successo
400Richiesta malformata — controlla i parametri
401API key mancante o non valida
402Piano non sufficiente o crediti esauriti
429Troppe richieste — rispetta il rate limit

Endpoint

GET/api/v1/sites

Restituisce la lista di tutti i siti collegati al tuo account.

Esempio di richiesta

curl -H "Authorization: Bearer al_xxxx" \
  https://audiolayer.it/api/v1/sites

Risposta

{
  "sites": [
    {
      "id": "3f2a1b4c-...",
      "name": "Il mio Blog",
      "url": "https://miosito.it",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}
GET/api/v1/articles?siteId={id}

Lista gli articoli di un sito con il loro stato di conversione audio.

Parametri

NomeTipoRichiestoDescrizione
siteIdstring (uuid)SìID del sito di cui listare gli articoli

Esempio di richiesta

curl -H "Authorization: Bearer al_xxxx" \
  "https://audiolayer.it/api/v1/articles?siteId=3f2a1b4c-..."

Risposta

{
  "articles": [
    {
      "id": "a1b2c3d4-...",
      "title": "Come usare AudioLayer",
      "url": "https://miosito.it/come-usare-audiolayer",
      "status": "ready",
      "audioUrl": "https://cdn.audiolayer.it/audio/a1b2c3d4-....mp3",
      "durationSeconds": 142,
      "createdAt": "2024-02-01T09:15:00Z"
    }
  ]
}
POST/api/v1/articles

Avvia la conversione di un articolo in audio. Richiede un piano a pagamento e crediti disponibili.

Richiede piano Starter o Pro. Consuma 1 credito per articolo. Consigliato l'header opzionale Idempotency-Key (max 200 caratteri): se ritenti la stessa richiesta dopo un timeout di rete, ricevi il job originale senza consumare un secondo credito (risposta con deduplicated: true). Anche senza header, una richiesta duplicata per un articolo con conversione già in corso restituisce il job attivo senza addebito.

Corpo della richiesta

CampoTipoRichiestoDescrizione
articleIdstring (uuid)SìID dell'articolo da convertire
voiceIdstringNoID della voce da usare (es. openai:alloy). Se omesso, usa la voce di default.

Esempio di richiesta

curl -X POST \
  -H "Authorization: Bearer al_xxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ordine-1234-tentativo-1" \
  -d '{"articleId": "a1b2c3d4-...", "voiceId": "openai:nova"}' \
  https://audiolayer.it/api/v1/articles

Risposta

{
  "jobId": "j9k8l7m6-...",
  "status": "queued",
  "message": "Conversione avviata. Controlla lo stato con GET /api/v1/articles."
}

Prova l'API

Inserisci la tua API key e testa gli endpoint direttamente da questa pagina.

Rate limit

Piano Free: 60 richieste/minuto. Piano Starter: 300 richieste/minuto. Piano Pro: 1000 richieste/minuto. Le risposte includono gli header X-RateLimit-Remaining e X-RateLimit-Reset.