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 identificadas por nome com criptografia AES-256-GCM para diferentes casos de uso.

Criar chave de API#

Crie uma nova chave de API:

1. Acesse Configurações > Chaves de API
2. Clique em Add Key e selecione Ultralytics como provedor
3. Digite um nome para a chave (por exemplo, "Servidor de treinamento")
4. Clique em Create Key

Nome da chave#

Dê um nome descritivo à sua chave:

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

Exibição da chave#

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

Chaves de provedores para agentes e anotação#

A mesma guia Configurações > Chaves de API também armazena chaves para provedores de modelos externos usados por Agents e pelos modelos pagos em anotação guiada por classes; a anotação lê a chave salva no espaço de trabalho do conjunto de dados. Somente o proprietário do espaço de trabalho pode adicionar, substituir ou remover essas chaves; os membros da equipe podem ver quais provedores estão conectados. Peça ao proprietário para conectar um provedor que esteja faltando. Para conectar um provedor como proprietário:

1. Clique em Add Key.
2. Selecione o provedor correspondente ao modelo de linguagem ou de visão e linguagem do seu fluxo de trabalho, ou o modelo de anotação que você quer executar.
3. Cole a chave de API do provedor em API Key e clique em Save Key. O link Get an API key no diálogo abre a página de chaves do provedor.

Uma chave da Ultralytics não autentica em provedores de modelos externos. O uso do provedor é cobrado na conta do provedor associada à chave salva. Use o controle de edição da linha da chave para substituir uma chave de 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 criptografia AES-256-GCM, nunca em texto simples
• Os primeiros 11 caracteres (ul_ mais 8 caracteres hexadecimais) funcionam como prefixo de exibição, permitindo identificar uma chave sem expô-la

Usar chaves de API#

Variável de ambiente#

Defina sua chave como variável de ambiente:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Valide e salve a chave usando a YOLO CLI no Python>=3.11:

yolo login YOUR_API_KEY

Remova a chave salva com yolo logout.

Cabeçalhos HTTP#

Inclua a chave nas solicitações à API:

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

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

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

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

Treino remoto#

Ative o streaming de métricas com sua chave.

Instale ou atualize o pacote Ultralytics no 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

Consulte Treinamento na nuvem para ver o guia completo de treinamento remoto.

Gerenciar chaves#

Visualizar chaves#

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

Cada linha de chave mostra o nome da chave, o prefixo da chave, a data de criação, um botão para copiar a chave completa e um botão para remover (lixeira).

Revogar chave#

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

1. Encontre a chave na seção Chaves de API
2. Clique no botão para remover (lixeira)
3. Clique em Remove Key para confirmar

Gerar uma nova chave#

Se uma chave for 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 têm escopo limitado ao espaço de trabalho ativo no momento:

• Espaço de trabalho pessoal: as chaves autenticam como sua conta pessoal
• Espaço de trabalho da equipe: as chaves autenticam como o proprietário do espaço de trabalho da equipe, com todas as permissões de proprietário nesse espaço de trabalho

Ao alternar entre espaços de trabalho na barra lateral, a seção Chaves de API mostra as chaves daquele espaço de trabalho. Como uma chave de espaço de trabalho tem permissões de proprietário, somente o proprietário do espaço de trabalho pode criá-la, visualizá-la ou revogá-la. Consulte Equipes para ver detalhes sobre as funções.

Chaves de worker locais#

A conexão de um host local gera uma chave de worker separada. As chaves de worker são gerenciadas pela integração local, e não nesta guia, nunca aparecem junto com suas chaves de API e são revogadas ao desconectar o host — o que também cancela as tarefas enfileiradas e em execução desse host.

Práticas recomendadas de segurança#

Faça#

• Armazene as chaves em variáveis de ambiente
• Use chaves separadas para ambientes diferentes
• Revogue prontamente as chaves não utilizadas
• Alterne as chaves periodicamente
• Use nomes descritivos para identificar a finalidade das chaves

Não#

• Não faça commit de chaves no controle de versão
• Não compartilhe chaves entre aplicações
• Não registre chaves na saída da aplicação
• Não incorpore chaves no código do lado do cliente

Rotação de chaves#

Faça a rotação periódica das chaves 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. Certifique-se de usar Python>=3.11 e 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 tem acesso adequado ao workspace
2. Verifique se a chave pertence ao workspace correto
3. Se você estiver gerenciando chaves em um workspace de equipe, confirme se é o proprietário do workspace — as outras funções recebem Workspace owner access required
4. Crie uma nova chave, se necessário

Limite de solicitações atingido#

Error: Rate limit exceeded

Soluções:

1. Reduza a frequência das solicitações — consulte a tabela de limites de solicitações para ver os limites por categoria
2. Implemente um recuo exponencial usando o cabeçalho Retry-After
3. Use um endpoint dedicado quando precisar de capacidade de inferência isolada

Perguntas frequentes#