Chaves de API#

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

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

Nome da Chave#

Dê à sua chave um nome descritivo:

• training-server - Para máquinas de treinamento 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:

Formato da Chave#

As chaves de API seguem este formato:

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

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

Segurança da Chave#

• As chaves são armazenadas com criptografia AES-256-GCM
• A autenticação usa um hash SHA-256 para uma pesquisa indexada rápida
• Valores de chave completos nunca são armazenados em texto simples

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/...

Veja a Referência da REST API para 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

Veja Treinamento na Nuvem para o guia completo de treinamento remoto.

Gerenciar Chaves#

Ver Chaves#

Todas as chaves estão listadas na aba Settings > API Keys:

Cada cartão de chave mostra o nome da chave, o valor da chave copiável, o tempo de criação relativo, a contagem de utilizações 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

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
• Workspace de equipe: As chaves autenticam dentro do contexto da equipe

Ao alternar workspaces na barra lateral, a seção API Keys mostra as chaves para aquele workspace. A função de Editor ou superior é necessária para gerenciar chaves de API do workspace. Veja Equipes para detalhes sobre as funções.

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

Solução de Problemas#

Erro de Chave Inválida#

Error: Invalid API key

Soluções:

1. Verifique 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.104

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. 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 — veja a tabela de limites de taxa para limites por endpoint
2. Implemente recuo exponencial usando o cabeçalho Retry-After
3. Usa um endpoint dedicado quando precisares de capacidade de inferência isolada

FAQ#

Quantas chaves posso criar?#

Não há um limite rígido para chaves de API. Crie quantas forem necessárias para diferentes aplicações e ambientes.

As chaves expiram?#

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

Posso ver minha chave após a criação?#

Sim, os valores completos das chaves estão visíveis na lista de chaves em Settings > API Keys. A plataforma descriptografa e exibe suas chaves para que você possa copiá-las a qualquer momento.

As chaves são específicas da região?#

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

Posso compartilhar chaves com membros da equipe?#

Melhor prática: peça para cada membro da equipe criar sua própria chave. Para espaços de trabalho de equipe, cada membro com a função de Editor ou superior pode criar chaves restritas a esse espaço de trabalho.