Link to this sectionAPI 키#

Ultralytics Platform API 키를 통해 원격 학습, 추론 및 자동화를 위한 안전한 프로그래밍 방식의 액세스가 가능합니다. 다양한 사용 사례를 위해 AES-256-GCM 암호화가 적용된 이름을 지정한 키를 생성하십시오.

Link to this sectionAPI 키 생성#

새 API 키 생성:

1. **설정 > API 키(Settings > API Keys)**로 이동합니다.
2. **키 생성(Create Key)**을 클릭합니다.
3. 키 이름을 입력합니다(예: "Training Server")
4. **키 생성(Create Key)**을 클릭합니다.

Link to this section키 이름#

키에 설명적인 이름을 지정하십시오:

• training-server - 원격 학습 머신용
• ci-pipeline - CI/CD 통합용
• local-dev - 로컬 개발용

Link to this section키 표시#

생성 후, 키는 한 번만 표시됩니다:

Link to this section키 형식#

API 키는 다음 형식을 따릅니다:

• 접두사(Prefix): ul_은 Ultralytics 키임을 식별합니다.
• 본문(Body): 40개의 무작위 16진수 문자
• 총합: 43자

Link to this section키 보안#

• 키는 AES-256-GCM 암호화로 저장됩니다.
• 인증은 빠른 접두사 조회 및 해시 비교를 위해 SHA-256 해시를 사용합니다.
• 전체 키 값은 일반 텍스트(plaintext)로 저장되지 않습니다.

Link to this sectionAPI 키 사용#

Link to this section환경 변수#

키를 환경 변수로 설정합니다:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

Link to this sectionYOLO CLI#

YOLO CLI를 사용하여 키를 설정합니다:

yolo settings api_key="YOUR_API_KEY"

Link to this section코드에서#

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"

Link to this sectionHTTP 헤더#

API 요청에 키를 포함합니다:

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

사용 가능한 모든 엔드포인트는 REST API 참조를 확인하십시오.

Link to this section원격 학습#

키를 사용하여 메트릭 스트리밍을 활성화하십시오.

pip install "ultralytics>=8.4.60"

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

전체 원격 학습 가이드는 클라우드 학습(Cloud Training)을 참조하십시오.

Link to this section키 관리#

Link to this section키 보기#

모든 키는 Settings > API Keys 탭에 나열됩니다:

각 키 카드에는 키 이름, 전체 복호화된 키 값(복사 가능), 상대적 생성 시간 및 취소(revoke) 버튼이 표시됩니다.

Link to this section키 취소#

위험에 노출되었거나 더 이상 필요하지 않은 키를 취소하십시오:

1. API 키 섹션에서 해당 키를 찾습니다.
2. 취소(Revoke)(휴지통) 버튼을 클릭합니다.
3. 취소를 확인합니다.

Link to this section키 재생성#

키가 노출된 경우:

1. 같은 이름으로 새 키를 생성합니다.
2. 애플리케이션을 업데이트합니다.
3. 이전 키를 취소합니다.

Link to this section워크스페이스 API 키#

API 키는 현재 활성화된 워크스페이스에 범위가 지정됩니다:

• 개인 워크스페이스(Personal workspace): 개인 계정으로 인증
• 팀 워크스페이스(Team workspace): 팀 컨텍스트 내에서 인증

사이드바에서 워크스페이스를 전환하면 API 키 섹션에 해당 워크스페이스의 키가 표시됩니다. 워크스페이스 API 키를 관리하려면 편집자(Editor) 이상의 역할이 필요합니다. 역할에 대한 자세한 내용은 팀(Teams)을 참조하십시오.

Link to this section보안 모범 사례#

Link to this section권장 사항(Do)#

• 키를 환경 변수에 저장하십시오.
• 환경별로 별도의 키를 사용하십시오.
• 사용하지 않는 키는 즉시 취소하십시오.
• 주기적으로 키를 교체(Rotate)하십시오.
• 키의 용도를 식별할 수 있도록 설명적인 이름을 사용하십시오.

Link to this section주의 사항(Don't)#

• 키를 버전 제어 시스템에 커밋하지 마십시오.
• 애플리케이션 간에 키를 공유하지 마십시오.
• 애플리케이션 로그에 키를 기록하지 마십시오.
• 클라이언트 측 코드에 키를 포함하지 마십시오.

Link to this section키 교체(Key Rotation)#

보안을 위해 주기적으로 키를 교체하십시오:

1. 같은 이름으로 새 키를 생성합니다.
2. 새 키를 사용하도록 애플리케이션을 업데이트합니다.
3. 애플리케이션이 올바르게 작동하는지 확인합니다.
4. 이전 키를 취소합니다.

Link to this section문제 해결#

Link to this section유효하지 않은 키 오류#

해결 방법:

1. 키가 (ul_ 접두사를 포함하여) 올바르게 복사되었는지 확인하십시오.
2. 키가 취소되지 않았는지 확인하십시오.
3. 환경 변수가 설정되었는지 확인하십시오.
4. ultralytics>=8.4.60 버전을 사용 중인지 확인하십시오.

Link to this section권한 거부#

해결 방법:

1. 리소스 소유자이거나 적절한 워크스페이스 액세스 권한이 있는지 확인하십시오.
2. 키가 올바른 워크스페이스에 속해 있는지 확인하십시오.
3. 필요한 경우 새 키를 생성하십시오.

Link to this section요청 횟수 제한(Rate Limited)#

해결 방법:

1. 요청 빈도를 줄이십시오. 엔드포인트별 제한 사항은 요청 횟수 제한 표를 참조하십시오.
2. Retry-After 헤더를 사용하여 지수 백오프(exponential backoff)를 구현하십시오.
3. 무제한 추론 처리량을 위해 전용 엔드포인트를 사용하십시오.

Link to this sectionFAQ#

Link to this section키를 몇 개까지 생성할 수 있습니까?#

API 키 생성 개수에는 엄격한 제한이 없습니다. 다양한 애플리케이션 및 환경에 필요한 만큼 생성하십시오.

Link to this section키가 만료됩니까?#

키는 자동으로 만료되지 않습니다. 취소되기 전까지 유효합니다. 보안을 위해 키 교체(rotation)를 구현하는 것을 고려하십시오.

Link to this section생성 후에도 키를 확인할 수 있습니까?#

네, 전체 키 값은 Settings > API Keys의 키 목록에서 확인할 수 있습니다. 플랫폼이 키를 복호화하여 표시하므로 언제든지 복사할 수 있습니다.

Link to this section키가 지역별로 제한됩니까?#

키는 모든 지역에서 작동하지만, 계정이 속한 지역의 데이터에만 액세스할 수 있습니다.

Link to this section팀원들과 키를 공유할 수 있습니까?#

권장 사항: 각 팀원이 자신의 키를 직접 생성하십시오. 팀 워크스페이스의 경우, Editor 이상의 역할을 가진 모든 구성원이 해당 워크스페이스에 대한 키를 생성할 수 있습니다.