Usare l'API per sviluppatori e i webhook

La pagina API nel Dashboard offre l'accesso programmatico ad avatar, voci e generazione di audio e video. Apri Dashboard → API per URL base corrente, formato di autenticazione, gestione delle chiavi API, impostazioni webhook e link alla documentazione completa per sviluppatori.

Chi può creare una chiave API

L'accesso all'API per sviluppatori è disponibile con piani a pagamento. Se la scheda della chiave API indica che serve un piano, effettua l'upgrade tramite Billing prima di provare a crearla. Una chiave API è una credenziale segreta per software, non una password da condividere con una persona.

Creare e conservare una chiave API

1. Apri Dashboard → API e trova la scheda Developer API.

2. Inserisci un nome riconoscibile, ad esempio “production backend” o “staging integration”, poi seleziona Create.

3. Copia subito la chiave completa e conservala nel gestore di segreti della distribuzione o in una configurazione d'ambiente protetta.

4. Dopo aver chiuso la visualizzazione unica, il Dashboard conserva solo prefisso e metadati di uso; la chiave completa non può essere visualizzata di nuovo.

Tratta una chiave API come una password che può spendere i crediti dell'account. Non inserirla mai in codice browser, app mobile, screenshot, messaggi chat, repository pubblici o variabili d'ambiente lato client.

Autenticare una richiesta

La pagina API mostra URL base e formato dell'header Authorization. Invia la chiave solo da codice server affidabile con Authorization: Bearer <key>. Prima di creare un'integrazione, consulta la documentazione su endpoint, corpi delle richieste, polling delle attività, risposte, limiti di frequenza e codici di errore correnti.

Ruotare o revocare una chiave

1. Crea e distribuisci prima una chiave sostitutiva quando puoi farlo in sicurezza.

2. Aggiorna ogni servizio che usa la vecchia chiave e verifica che le sue richieste riescano.

3. Usa l'azione di revoca accanto alla vecchia chiave in Dashboard → API.

La revoca è irreversibile. Non revocare una chiave soltanto per vederne di nuovo il valore completo: creane una sostitutiva.

Configurare un webhook di generazione

1. In Dashboard → API inserisci nella scheda Webhook un endpoint HTTPS pubblico controllato dal tuo server.

2. Seleziona Save. Salvare un endpoint nuovo o modificato può mostrare una volta il segreto webhook; copialo e conservalo subito.

3. Sul server calcola HMAC-SHA256 sul corpo non elaborato della richiesta usando quel segreto e confrontalo con l'header X-Odrazio-Signature prima di accettare l'evento.

4. Usa l'evento per recuperare dal server la risorsa corrispondente o aggiornare il record del job. Una richiesta in ingresso non verificata non prova il completamento della generazione.

Modificare o rimuovere un webhook

Salvare un URL webhook modificato può ruotare il segreto, quindi aggiorna nello stesso momento la configurazione di verifica. Usa Remove quando non desideri più la consegna. L'URL deve essere pubblicamente raggiungibile via HTTPS; un indirizzo di sviluppo solo locale non può ricevere callback della piattaforma.