Un endpoint API, o punto di terminazione, è l’indirizzo preciso a cui un’API riceve richieste e restituisce risposte. È il punto in cui un’applicazione si connette a un server per richiedere dati o lanciare un comando. In una guida pubblicata sul suo blog, la società ElevenLabs dettaglia questo funzionamento a partire dalla sua interfaccia ElevenAPI.
Richieste, risposte e route
Un endpoint è una posizione digitale che un’API utilizza per ricevere richieste e inviare risposte. Le applicazioni client accedono alle risorse del server grazie a un URL collegato a questo endpoint. Ogni route associa un metodo HTTP, il protocollo di comunicazione del web, a un percorso di risorsa.
Lo scambio segue generalmente quattro fasi. Il client invia prima una richiesta HTTP comprendente un metodo, degli header, eventualmente dei parametri e un corpo di dati. Il server verifica le credenziali e i diritti di accesso, poi interroga i suoi database o esegue la logica di business. Restituisce quindi un payload in formato JSON, un formato di dati strutturato, accompagnato da un codice di stato HTTP. L’applicazione client sfrutta infine questi dati.
I termini API, endpoint e URL sono spesso usati insieme, ma non designano la stessa cosa. Un’API è l’insieme delle regole e dei contratti di dati che permettono a due applicazioni di comunicare. Un endpoint ne è un punto di ingresso preciso, mentre l’URL è l’indirizzo scritto completo che permette di localizzarlo sulla rete. Un’API comprende diversi endpoint, e un URL può contenere un protocollo, un nome di dominio, un percorso e dei parametri di query.
In un’API REST, le richieste GET leggono dati senza modificare le risorse del server, mentre le richieste POST ne creano o attivano azioni. Le richieste PUT o PATCH servono a modificare record esistenti, e DELETE a eliminarli. Secondo la guida, ElevenAPI si basa soprattutto su GET e POST, ai quali si aggiungono endpoint di streaming e WebSocket per l’audio in tempo reale. Ad esempio, la richiesta GET https://api.elevenlabs.io/v1/models recupera la lista dei modelli di sintesi vocale disponibili e le loro capacità. La richiesta POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id} invia un testo e un identificativo di modello, e restituisce audio in streaming.
Sicurezza degli endpoint
Ogni richiesta trasporta la chiave segreta nell’header xi-api-key. Queste chiavi a lunga durata devono rimanere su server sicuri e non devono mai apparire nel codice lato client, come in un browser o un’app mobile. Per le connessioni WebSocket lato client, il server genera un token monouso, che scade dopo 15 minuti e viene consumato al primo utilizzo.
La guida raccomanda anche di creare chiavi distinte per lo sviluppo, la pre-produzione e la produzione. Ogni chiave può essere limitata a certi endpoint, ad esempio alla trascrizione vocale per una chiave che non ha bisogno della sintesi. Possono essere fissati dei quote di crediti per chiave, e gli account aziendali possono limitare l’uso a certi indirizzi IP, funzione presentata come in anteprima. Le richieste provenienti da un altro indirizzo vengono quindi rifiutate con un errore HTTP 403. I limiti di velocità sono, secondo la fonte, basati sulla concorrenza, cioè sul numero di generazioni simultanee, e non su un quota per minuto.
Test e monitoraggio
Testare un endpoint fin dall’inizio permette di verificare l’autenticazione e la connettività prima di scrivere la logica applicativa. Una richiesta GET verso https://api.elevenlabs.io/v1/models, con l’header xi-api-key, basta a validare le credenziali e l’accesso di rete. Secondo la guida, questo test non consuma crediti fatturati sul conto.
Bisogna anche monitorare gli errori HTTP 429. Un errore too_many_concurrent_requests significa che l’account ha raggiunto il limite di concorrenza del suo piano: bisogna attendere la fine delle richieste in corso o passare a un piano superiore. Un errore system_busy indica invece una congestione temporanea della piattaforma, e un nuovo tentativo riesce generalmente.
