YOLO Vision 2026:

Chaves de API#

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

Ultralytics Platform Settings API Keys Tab Key List

Apenas Proprietário

Apenas o proprietário do workspace pode criar, ver ou revogar as API keys de um workspace, porque uma key se autentica como o proprietário do workspace. Membros com qualquer outra função veem uma nota na aba em vez da lista de keys. As API keys em si não podem criar ou revogar outras API keys. A única exceção são as On Premise worker keys, que são revogadas ao desconectar o host da integração On Premise.

Criar Chave de API#

Crie uma nova chave de API:

  1. Vá para Settings > API Keys
  2. Clique em Create Key
  3. Insira um nome para a chave (por exemplo, "Servidor de Treinamento")
  4. Clique em Create Key

Ultralytics Platform Settings API Keys Tab Create API Key Dialog

Nome da Chave#

Dê à sua chave um nome descritivo:

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

Exibição da Chave#

Após a criação, a chave é exibida em uma caixa de diálogo de confirmação:

Ultralytics Platform Settings API Keys Tab API Key Created Copy Dialog

Copie Sua Chave

Copia a tua chave após a criação para facilitar a consulta. As chaves também ficam visíveis na lista de chaves — a plataforma desincripta e apresenta os valores completos das chaves para que as possas copiar a qualquer momento.

Formato da Chave#

As chaves de API seguem este formato:

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

Segurança da Chave#

  • As keys são armazenadas com criptografia AES-256-GCM, nunca em texto plano
  • Os primeiros 11 caracteres (ul_ mais 8 caracteres hexadecimais) atuam como um prefixo de exibição, para que uma key possa ser identificada sem exibi-la

Usando Chaves de API#

Variável de ambiente#

Defina sua chave como uma variável de ambiente:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Valida e guarda a chave utilizando a CLI do YOLO:

yolo login YOUR_API_KEY

Remove a chave guardada com yolo logout.

Cabeçalhos HTTP#

Inclua a chave em solicitações de API:

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

Ou passa-a para o Python SDK (pip install "ultralytics-platform>=0.1.5"), que também lê ULTRALYTICS_API_KEY:

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

Consulta a REST API Reference para ver todos os endpoints disponíveis.

Treinamento Remoto#

Habilite o streaming de métricas com sua chave.

Instala ou atualiza o pacote Ultralytics 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 Cloud Training para o guia completo de treino remoto.

Gerenciar Chaves#

Ver Chaves#

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

Cada cartão de key mostra o nome da key, o valor da key copiável, o tempo relativo de criação e um botão de revogação.

Revogar Chave#

Revogue uma chave que esteja comprometida ou que não seja mais necessária:

  1. Encontre a chave na seção API Keys
  2. Clique no botão Revoke (lixeira)
  3. Confirme a revogação
Efeito Imediato

A revogação é imediata e permanente — o registro da key é excluído, não desativado. Quaisquer aplicações que usem a key pararão de funcionar.

Regenerar Chave#

Se uma chave estiver comprometida:

  1. Crie uma nova chave com o mesmo nome
  2. Atualize suas aplicações
  3. Revogue a chave antiga

Chaves de API do Workspace#

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

  • Workspace pessoal: As chaves autenticam como sua conta pessoal
  • Team workspace: As keys se autenticam como o proprietário do team workspace, com permissões completas de proprietário nesse workspace

Ao alternar workspaces na barra lateral, a seção API Keys mostra as keys para esse workspace. Como uma workspace key possui permissões de proprietário, apenas o proprietário do workspace pode criar, ver ou revogar uma. Veja Teams para detalhes de funções.

On Premise Worker Keys#

Conectar um host On Premise gera uma worker key separada. As worker keys são gerenciadas a partir da integração On Premise em vez desta aba, nunca são listadas junto com suas API keys e são revogadas desconectando o host — o que também cancela os jobs na fila e em execução desse host.

Melhores Práticas de Segurança#

Faça#

  • Armazene chaves em variáveis de ambiente
  • Use chaves separadas para diferentes ambientes
  • Revogue chaves não utilizadas prontamente
  • Rotacione as chaves periodicamente
  • Use nomes descritivos para identificar os propósitos das chaves

Não faça#

  • Confirmar chaves no controle de versão
  • Compartilhar chaves entre aplicações
  • Registrar chaves na saída da aplicação
  • Embutir chaves no código do lado do cliente

Rotação de Chaves#

Rotacione as chaves periodicamente por segurança:

  1. Crie uma nova chave com o mesmo nome
  2. Atualize as aplicações para usar a nova chave
  3. Verifique se as aplicações funcionam corretamente
  4. Revogue a chave antiga
Cronograma de Rotação

Considere rotacionar as chaves a cada 90 dias para aplicações sensíveis.

Soluçã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. Verifique se a chave não foi revogada
  3. Confirme se a variável de ambiente está definida
  4. Certifica-te de que estás a usar ultralytics>=8.4.120

Permissão Negada#

Error: Permission denied for this operation

Soluções:

  1. Verifique se você é o proprietário do recurso ou se possui acesso apropriado ao workspace
  2. Verifique se a chave pertence ao workspace correto
  3. Se você estiver gerenciando keys em um team workspace, confirme que você é o proprietário do workspace — outras funções recebem Workspace owner access required
  4. Crie uma nova chave, se necessário

Limite de Taxa (Rate Limited)#

Error: Rate limit exceeded

Soluções:

  1. Reduza a frequência de solicitações — consulte a rate limit table para limites por categoria
  2. Implementa o recuo exponencial utilizando o cabeçalho Retry-After
  3. Usa um dedicated endpoint quando precisares de capacidade de inferência isolada

FAQ#

  • Não há um limite rígido para 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 a rotação por segurança.

  • Sim, os valores completos das chaves estão visíveis na lista de chaves em Settings > API Keys. O Platform desencripta e mostra as tuas chaves para que as possas copiar a qualquer momento.

  • As chaves funcionam em todas as regiões, mas acessam apenas os dados na região da sua conta.

  • Não — uma key de team workspace se autentica como o proprietário do workspace, portanto, apenas o proprietário pode criar ou ver uma, e compartilhá-la transfere permissões de proprietário. Peça para cada membro criar uma key em seu próprio workspace pessoal e peça ao proprietário para gerar uma workspace key dedicada para automação compartilhada como CI.

  • Não. Uma key pertence ao workspace em que foi criada e alcança apenas os recursos desse workspace. Crie uma key separada para cada workspace que você automatizar.

Contribuidores
GLglenn-jocher14SEsergiuwaxmann2LAlaodouya1MYmykolaxboiko1LALaughing-q1

Comentários