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 Configurações > Chaves de API
2. Clique em Criar chave
3. Insira um nome para a chave (por exemplo, "Servidor de Treinamento")
4. Clique em Criar chave

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 uma vez:

Formato da chave

As chaves de API seguem este formato:

• Prefixo: ul_ identifica as 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 hash SHA-256 para busca rápida de prefixo e comparação de hash
• 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

Defina a chave usando a YOLO CLI:

yolo settings api_key="YOUR_API_KEY"

No código

Use a chave em seus scripts Python:

import os

# From environment (recommended)
api_key = os.environ.get("ULTRALYTICS_API_KEY")

# Or directly (not recommended for production)
api_key = "YOUR_API_KEY"

Cabeçalhos HTTP

Inclua a chave em solicitações de API:

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

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

Treinamento Remoto

Habilite o streaming de métricas com sua chave.

pip install "ultralytics>=8.4.35"

export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1

Veja Treinamento em nuvem para o guia completo de treinamento remoto.

Gerenciar chaves

Ver chaves

All keys are listed on the Settings > API Keys tab:

Cada cartão de chave mostra o nome da chave, o valor total descriptografado (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 Chaves de API
2. Clique no botão Revogar (lixeira)
3. Confirme a revogação

Regerar chave

Se uma chave estiver comprometida:

1. Crie uma nova chave com o mesmo nome
2. Atualize seus aplicativos
3. Revogue a chave antiga

Chaves de API do espaço de trabalho

As chaves de API estão vinculadas ao espaço de trabalho atualmente ativo:

• Espaço de trabalho pessoal: As chaves autenticam como sua conta pessoal
• Espaço de trabalho da equipe: As chaves autenticam dentro do contexto da equipe

Ao alternar espaços de trabalho na barra lateral, a seção de Chaves de API mostra as chaves para esse espaço de trabalho. É necessária a função de Editor ou superior para gerenciar chaves de API do espaço de trabalho. Consulte Equipes para detalhes de funções.

Melhores práticas de segurança

Fazer

• Armazenar chaves em variáveis de ambiente
• Usar chaves separadas para diferentes ambientes
• Revogar chaves não utilizadas prontamente
• Rotacionar chaves periodicamente
• Usar nomes descritivos para identificar os propósitos das chaves

Não fazer

• Confirmar chaves em controle de versão
• Compartilhar chaves entre aplicativos
• Registrar chaves na saída do aplicativo
• Incorporar 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 os aplicativos para usar a nova chave
3. Verifique se os aplicativos funcionam corretamente
4. Revogue a chave antiga

Resolução de Problemas

Erro de chave inválida

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. Certifique-se de estar usando ultralytics>=8.4.35

Permissão negada

Soluções:

1. Verifique se você é o proprietário do recurso ou se tem acesso apropriado ao espaço de trabalho
2. Verifique se a chave pertence ao espaço de trabalho correto
3. Crie uma nova chave, se necessário

Limite de taxa atingido

Soluções:

1. Reduza a frequência de solicitações — consulte a tabela de limite de taxa para limites por endpoint
2. Implemente backoff exponencial usando o cabeçalho Retry-After
3. Use um endpoint dedicado para throughput de inferência ilimitado

FAQ

Quantas chaves posso criar?

Não há um limite rígido para as chaves de API. Crie quantas forem necessárias para diferentes aplicativos 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 sã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 por região?

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

Posso compartilhar chaves com membros da equipe?

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