Um endpoint de API, ou ponto de terminação, é o endereço preciso onde uma API recebe pedidos e envia respostas. É o ponto onde uma aplicação se liga a um servidor para solicitar dados ou executar um comando. Num guia publicado no seu blog, a empresa ElevenLabs detalha este funcionamento a partir da sua interface ElevenAPI.
- Um endpoint é o endereço onde uma API recebe pedidos e envia respostas.
- As chaves secretas devem ficar em servidores seguros, nunca no código do cliente.
- Cada chave pode ser limitada a certos endpoints e a quotas de créditos.
- Um pedido GET a /v1/models valida as credenciais sem consumir créditos.
Pedidos, respostas e rotas
Um endpoint é uma localização digital que uma API utiliza para receber pedidos e enviar respostas. As aplicações clientes acedem aos recursos do servidor através de um URL associado a esse endpoint. Cada rota associa um método HTTP, o protocolo de comunicação da web, a um caminho de recurso.
A troca segue geralmente quatro etapas. O cliente envia primeiro um pedido HTTP que inclui um método, cabeçalhos, eventualmente parâmetros e um corpo de dados. O servidor verifica as credenciais e os direitos de acesso, depois consulta as suas bases de dados ou executa a lógica de negócio. De seguida, devolve uma carga útil no formato JSON, um formato de dados estruturado, acompanhada de um código de estado HTTP. A aplicação cliente utiliza finalmente esses dados.
Os termos API, endpoint e URL são frequentemente usados em conjunto, mas não designam a mesma coisa. Uma API é o conjunto de regras e contratos de dados que permitem que duas aplicações comuniquem. Um endpoint é um ponto de entrada preciso, enquanto o URL é o endereço escrito completo que permite localizá-lo na rede. Uma API contém vários endpoints, e um URL pode conter um protocolo, um nome de domínio, um caminho e parâmetros de consulta.
Numa API REST, os pedidos GET leem dados sem modificar os recursos do servidor, enquanto os pedidos POST criam dados ou desencadeiam ações. Os pedidos PUT ou PATCH servem para modificar registos existentes, e DELETE para os eliminar. Segundo o guia, a ElevenAPI baseia-se sobretudo em GET e POST, aos quais se juntam endpoints de streaming e WebSocket para áudio em tempo real. Por exemplo, o pedido GET https://api.elevenlabs.io/v1/models obtém a lista dos modelos de síntese vocal disponíveis e as suas capacidades. O pedido POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id} envia um texto e um identificador de modelo, e devolve áudio em streaming.
Proteger os endpoints
Cada pedido transporta a chave secreta no cabeçalho xi-api-key. Estas chaves de longa duração devem permanecer em servidores seguros e nunca aparecer no código do lado do cliente, como num navegador ou numa aplicação móvel. Para as ligações WebSocket do lado do cliente, o servidor gera um token de uso único, que expira ao fim de 15 minutos e é consumido na primeira utilização.
O guia recomenda também criar chaves distintas para o desenvolvimento, pré-produção e produção. Cada chave pode ser limitada a certos endpoints, por exemplo, à transcrição vocal para uma chave que não precisa da síntese. Podem ser definidos quotas de créditos por chave, e as contas empresariais podem restringir o uso a determinados endereços IP, funcionalidade apresentada como em pré-visualização. Os pedidos provenientes de outro endereço são então rejeitados com um erro HTTP 403. Os limites de débito são, segundo a fonte, baseados na concorrência, ou seja, no número de gerações simultâneas, e não num quota por minuto.
Testar e monitorizar
Testar um endpoint desde o início permite verificar a autenticação e a conectividade antes de escrever a lógica da aplicação. Um pedido GET para https://api.elevenlabs.io/v1/models, com o cabeçalho xi-api-key, basta para validar as credenciais e o acesso à rede. Segundo o guia, este teste não consome créditos faturados na conta.
É também necessário monitorizar os erros HTTP 429. Um erro too_many_concurrent_requests significa que a conta atingiu o limite de concorrência da sua oferta: é necessário aguardar o fim dos pedidos em curso ou mudar para uma oferta superior. Um erro system_busy indica, por outro lado, uma congestão temporária da plataforma, e uma nova tentativa geralmente tem sucesso.
