Chaves de API
As chaves API da Plataforma Ultralytics permitem acesso programático seguro para treinamento remoto, inferência e automação. Crie chaves com escopo definido e permissões específicas para diferentes casos de uso.
Criar Chave de API
Criar uma nova chave API:
- Vá para Configurações > Chaves de API
- Clique em Criar Chave
- Insira um nome para a chave
- Selecione os escopos de permissão
- Clique em Criar
Nome da Chave
Atribua um nome descritivo à sua chave:
training-server- Para máquinas de treinamento remotoci-pipeline- Para integração CI/CDmobile-app- Para aplicações móveis
Escopos de Permissão
Selecione os escopos para limitar as permissões da chave:
| Escopo | Permissões |
|---|---|
| treino | Iniciar treinamento, transmitir métricas |
| modelos | Carregar, baixar, excluir modelos |
| conjuntos de dados | Aceder e modificar conjuntos de dados |
| leitura | Acesso somente leitura a todos os recursos |
| gravação | Acesso total de gravação |
| admin | Gerenciamento de conta (use com cautela) |
Privilégio Mínimo
Crie chaves apenas com as permissões necessárias. Use chaves separadas para diferentes aplicações.
Exibição da Chave
Após a criação, a chave é exibida uma única vez:
Copie Sua Chave
A chave completa é exibida apenas uma vez. Copie-a imediatamente e armazene-a de forma segura. Não será possível recuperá-la posteriormente.
Formato da Chave
As chaves de API seguem este formato:
ul_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
- Prefixo:
ul_identifica chaves Ultralytics - Corpo: 40 caracteres hexadecimais aleatórios
- Total: 43 caracteres
Usando Chaves de API
Variável de Ambiente
Defina sua chave como uma variável de ambiente:
export ULTRALYTICS_API_KEY="ul_your_key_here"
$env:ULTRALYTICS_API_KEY = "ul_your_key_here"
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 = "ul_your_key_here"
Cabeçalhos HTTP
Inclua a chave em requisições de API:
curl -H "Authorization: Bearer ul_your_key_here" \
https://platform.ultralytics.com/api/...
Treinamento Remoto
Habilite o streaming de métricas com sua chave.
Requisito de Versão do Pacote
A integração da plataforma requer ultralytics>=8.4.0. Versões anteriores NÃO funcionarão com a Plataforma.
pip install "ultralytics>=8.4.0"
export ULTRALYTICS_API_KEY="ul_your_key_here"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1
Gerenciar Chaves
Visualizar Chaves
Todas as chaves estão listadas em Configurações > Chaves de API:
| Coluna | Descrição |
|---|---|
| Nome | Identificador da chave |
| Escopos | Permissões atribuídas |
| Criado em | Data de criação |
| Último Uso | Uso mais recente |
Revogar Chave
Revogar uma chave comprometida ou que não é mais necessária:
- Clique no menu da chave
- Selecione Revogar
- Confirmar revogação
Efeito Imediato
A revogação é imediata. Quaisquer aplicações que utilizem a chave deixarão de funcionar.
Regenerar Chave
Se uma chave for comprometida:
- Criar uma nova chave com os mesmos escopos
- Atualizar suas aplicações
- Revogar a chave antiga
Melhores Práticas de Segurança
Fazer
- Armazenar chaves em variáveis de ambiente
- Utilizar chaves separadas para diferentes ambientes
- Revogar chaves não utilizadas prontamente
- Utilizar os escopos mínimos necessários
- Rotacionar chaves periodicamente
Não Fazer
- Fazer commit de chaves para controle de versão
- Compartilhar chaves entre aplicações
- Utilizar escopo de administrador desnecessariamente
- Registrar chaves na saída da aplicação
- Incorporar chaves em código do lado do cliente
Rotação de Chaves
Rotacionar chaves periodicamente por segurança:
- Criar nova chave com os mesmos escopos
- Atualizar aplicações para usar a nova chave
- Verificar se as aplicações funcionam corretamente
- Revogar chave antiga
Cronograma de Rotação
Considere rotacionar 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:
- Verificar se a chave foi copiada corretamente
- Verificar se a chave não foi revogada
- Garantir que a chave possui os escopos necessários
- Confirmar que a variável de ambiente está definida
Permissão Negada
Error: Permission denied for this operation
Soluções:
- Verificar se os escopos da chave incluem a permissão necessária
- Verificar se você é o proprietário do recurso
- Criar nova chave com os escopos corretos
Limite de Taxa Excedido
Error: Rate limit exceeded
Soluções:
- Reduzir a frequência de requisições
- Implementar backoff exponencial
- Contactar o suporte para aumento de limite
FAQ
Quantas chaves posso criar?
Não há 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 para segurança.
Posso ver minha chave após a criação?
Não, a chave completa é exibida apenas uma vez na criação. Se perdida, crie uma nova chave e revogue a antiga.
As chaves são específicas da região?
As chaves funcionam em todas as regiões, mas acessam dados apenas na região da sua conta.
Posso partilhar chaves com membros da equipa?
Melhor prática: Cada membro da equipe deve criar sua própria chave. Isso permite:
- track de atividade individual
- Revogação seletiva
- Controle de acesso adequado
