Ultralytics YOLO27:

Chaves de API#

As chaves de API da Ultralytics Platform permitem acesso programático seguro para treino remoto, inferência e automação. Cria chaves nomeadas com encriptação AES-256-GCM para diferentes casos de utilização.

Ultralytics Platform Settings API Keys Tab Key List

Apenas o proprietário

Apenas o proprietário do workspace pode criar, ver ou revogar as chaves de API do Ultralytics de um workspace, porque essas chaves autenticam como o proprietário do workspace. Outros membros não podem ver essa lista de chaves. Eles podem ver o status de conexão de provedores externos, mas não podem ver as chaves completas dos provedores nem alterar essas conexões. As chaves de API em si não podem criar ou revogar outras chaves de API. A única exceção são as chaves de worker On Premise, que são revogadas ao desconectar o host da integração On Premise.

Criar chave de API#

Cria uma nova chave de API:

  1. Vai a Settings > API Keys
  2. Clica em Add Key e seleciona Ultralytics como o provedor
  3. Introduz um nome para a chave (por exemplo, "Training Server")
  4. Clica em Create Key

Ultralytics Platform Settings API Keys Tab Create API Key Dialog

Nome da chave#

Dá um nome descritivo à tua chave:

  • training-server - Para máquinas de treino remoto
  • ci-pipeline - Para integração de CI/CD
  • local-dev - Para desenvolvimento local

Apresentação da chave#

Após a criação, a chave é apresentada numa caixa de diálogo de confirmação:

Ultralytics Platform Settings API Keys Tab API Key Created Copy Dialog

Copia a tua chave

Copia a tua chave após a criação para facilitar a consulta. Também podes usar o botão de cópia na lista de chaves a qualquer momento; a lista exibe apenas o prefixo de cada chave.

Chaves de Provedor para Agentes#

A mesma aba Settings > API Keys também armazena chaves para provedores de modelos externos usados por Agentes. Apenas o proprietário do workspace pode adicionar, substituir ou remover essas chaves; os membros da equipe podem ver quais provedores estão conectados. Pede ao proprietário para conectar um provedor ausente. Para conectar um provedor como o proprietário:

  1. Clica em Add Key.
  2. Seleciona o provedor correspondente ao modelo de linguagem ou de visão e linguagem do teu fluxo de trabalho.
  3. Cula a chave de API desse provedor em API Key, depois clica em Save Key. O link Get an API key do diálogo abre a página de chaves do provedor.

Uma chave do Ultralytics não autentica provedores de modelos externos. O uso do provedor é cobrado através da conta do provedor associada à chave salva. Usa o controle de edição da linha da chave para substituir uma chave de provedor.

Caixa de diálogo Adicionar Chave de API da Plataforma Ultralytics com o Google Gemini selecionado como o provedor

Formato da chave#

As chaves de API seguem este formato:

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4
  • Prefixo: ul_ identifica as chaves da Ultralytics
  • Corpo: 40 caracteres hexadecimais aleatórios
  • Total: 43 caracteres

Segurança das chaves#

  • As chaves são armazenadas com encriptação AES-256-GCM, nunca em texto simples
  • Os primeiros 11 caracteres (ul_ mais 8 caracteres hexadecimais) funcionam como um prefixo de apresentação, permitindo identificar uma chave sem a expor

Utilizar chaves de API#

Variável de ambiente#

Define a tua chave como uma variável de ambiente:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Valida e salva a chave usando a YOLO CLI em Python>=3.11:

yolo login YOUR_API_KEY

Remove a chave guardada com yolo logout.

Cabeçalhos HTTP#

Inclui a chave nos pedidos à API:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/...

Ou passa-a para o SDK Python (pip install "ultralytics-platform>=0.1.45"), que lê ULTRALYTICS_API_KEY ou a chave guardada por yolo login quando api_key é omitido:

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

Consulta a Referência da REST API para veres todos os endpoints disponíveis.

Treinamento remoto#

Ativa o streaming de métricas com a tua chave.

Instala ou atualiza o pacote Ultralytics em Python>=3.11 antes de começar:

pip install -U ultralytics
export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1

Consulta Treino na Cloud para veres o guia completo de treino remoto.

Gerir chaves#

Ver chaves#

Todas as chaves estão listadas no separador Settings > API Keys:

Cada cartão de chave mostra o nome da chave, o valor da chave que pode ser copiado, o tempo relativo desde a criação e um botão para a revogar.

Revogar chave#

Revoga uma chave que tenha sido comprometida ou que já não seja necessária:

  1. Localiza a chave na secção API Keys
  2. Clica no botão Revoke (caixote do lixo)
  3. Confirma a revogação
Efeito imediato

A revogação é imediata e permanente — o registo da chave é eliminado, não desativado. Todas as aplicações que utilizem a chave deixarão de funcionar.

Regenerar chave#

Se uma chave tiver sido comprometida:

  1. Cria uma nova chave com o mesmo nome
  2. Atualiza as tuas aplicações
  3. Revoga a chave antiga

Chaves de API do workspace#

As chaves de API estão associadas ao workspace atualmente ativo:

  • Workspace pessoal: As chaves autenticam a tua conta pessoal
  • Workspace de equipa: As chaves autenticam o proprietário do workspace da equipa, com todas as permissões do proprietário nesse workspace

Ao mudares de workspace na barra lateral, a secção API Keys mostra as chaves desse workspace. Como uma chave de workspace inclui permissões de proprietário, apenas o proprietário do workspace pode criá-la, vê-la ou revogá-la. Consulta Equipas para veres os detalhes das funções.

Chaves de worker On Premise#

Ao ligares um host On Premise, é criada uma chave de worker separada. As chaves de worker são geridas a partir da integração On Premise, e não deste separador, nunca são listadas juntamente com as tuas chaves de API e são revogadas ao desligar o host — o que também cancela os trabalhos desse host que estejam na fila ou em execução.

Práticas recomendadas de segurança#

Faz#

  • Armazena as chaves em variáveis de ambiente
  • Utiliza chaves separadas para ambientes diferentes
  • Revoga prontamente as chaves não utilizadas
  • Roda as chaves periodicamente
  • Utiliza nomes descritivos para identificar as finalidades das chaves

Não faças#

  • Faças commit das chaves no controlo de versões
  • Partilhes chaves entre aplicações
  • Registes chaves na saída da aplicação
  • Incorporar chaves no código do lado do cliente

Rotação de chaves#

Roda as chaves periodicamente para garantir a segurança:

  1. Cria uma nova chave com o mesmo nome
  2. Atualiza as aplicações para utilizarem a nova chave
  3. Verifica se as aplicações funcionam corretamente
  4. Revoga a chave antiga
Calendário de rotação

Considera rodar as chaves a cada 90 dias para aplicações sensíveis.

Resolução de problemas#

Erro de chave inválida#

Error: Invalid API key

Soluções:

  1. Verifica se a chave foi copiada corretamente (incluindo o prefixo ul_)
  2. Verifica se a chave não foi revogada
  3. Confirma se a variável de ambiente está definida
  4. Garante que estás a usar Python>=3.11 e ultralytics>=8.4.120

Permissão negada#

Error: Permission denied for this operation

Soluções:

  1. Verifica se és o proprietário do recurso ou se tens acesso adequado ao workspace
  2. Verifica se a chave pertence ao workspace correto
  3. Se estiveres a gerir chaves num workspace de equipa, confirma que és o proprietário do workspace — as outras funções recebem Workspace owner access required
  4. Cria uma nova chave, se necessário

Limite de pedidos atingido#

Error: Rate limit exceeded

Soluções:

  1. Reduz a frequência dos pedidos — consulta a tabela de limites de pedidos para veres os limites por categoria
  2. Implementa um recuo exponencial utilizando o cabeçalho Retry-After
  3. Utiliza um endpoint dedicado quando precisares de capacidade de inferência isolada

Perguntas frequentes#

  • Não há um limite fixo para o número de chaves de API. Crie quantas forem necessárias para diferentes aplicações e ambientes.

  • As chaves não expiram automaticamente. Elas permanecem válidas até serem revogadas. Considere implementar uma rotação por motivos de segurança.

  • Sim, os valores completos das chaves ficam visíveis na lista de chaves em Settings > API Keys. A Plataforma desencripta e apresenta as suas chaves para que possa copiá-las a qualquer momento.

  • As chaves funcionam em todas as regiões, mas só acedem aos dados da região da sua conta.

  • Não — uma chave de espaço de trabalho de equipa autentica-se como o proprietário do espaço de trabalho, por isso apenas o proprietário pode criar ou ver uma, e partilhá-la transfere as permissões de proprietário. Em vez disso, peça a cada membro para criar uma chave no seu próprio espaço de trabalho pessoal e peça ao proprietário para criar uma chave de espaço de trabalho dedicada para automações partilhadas, como CI.

  • Não. Uma chave pertence ao espaço de trabalho onde foi criada e só acede aos recursos desse espaço de trabalho. Crie uma chave separada para cada espaço de trabalho que automatizar.

Contribuidores
GLglenn-jocher17RAraimbekovm2SEsergiuwaxmann2LAlaodouya1MYmykolaxboiko1LALaughing-q1

Comentários