Link to this sectionAPI Keys#

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

Link to this sectionAPI 키 생성#

새 API 키 생성:

1. 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진수 문자
• Total: 43자

Link to this section키 보안#

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

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 Reference를 참조하십시오.

Link to this section원격 학습(Remote Training)#

키로 메트릭 스트리밍을 활성화하십시오.

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 탭에 나열됩니다:

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

Link to this section키 취소#

손상되었거나 더 이상 필요하지 않은 키를 취소하십시오:

1. API Keys 섹션에서 해당 키를 찾으십시오.
2. Revoke(휴지통) 버튼을 클릭하십시오.
3. 취소를 확인하십시오.

Link to this section키 재생성#

키가 손상된 경우:

1. 같은 이름으로 새 키를 생성하십시오.
2. 애플리케이션을 업데이트하십시오.
3. 이전 키를 취소하십시오.

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

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

• 개인 워크스페이스: 키가 개인 계정으로 인증됩니다.
• 팀 워크스페이스: 키가 팀 컨텍스트 내에서 인증됩니다.

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

Link to this section보안 모범 사례#

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

• 키를 환경 변수에 저장하십시오.
• 환경별로 별도의 키를 사용하십시오.
• 사용하지 않는 키는 즉시 취소하십시오.
• 주기적으로 키를 순환시키십시오.
• 설명적인 이름을 사용하여 키 용도를 식별하십시오.

Link to this section금지 사항(Don't)#

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

Link to this section키 순환#

보안을 위해 주기적으로 키를 순환시키십시오:

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속도 제한#

해결 방법:

1. 요청 빈도를 줄이십시오. 엔드포인트별 제한은 rate limit table을 참조하십시오.
2. Retry-After 헤더를 사용하여 지수 백오프를 구현하십시오.
3. 제한 없는 추론 처리량을 위해 전용 엔드포인트를 사용하십시오.

Link to this sectionFAQ#

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

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

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

키는 자동으로 만료되지 않습니다. 취소될 때까지 유효합니다. 보안을 위해 주기적으로 키를 순환시키는 것을 고려하십시오.

Link to this section생성 후 키를 다시 볼 수 있습니까?#

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

Link to this section키가 지역별로 고정되어 있습니까?#

키는 지역에 관계없이 작동하지만, 계정의 지역 내 데이터에만 액세스할 수 있습니다.

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

더 나은 방법: 각 팀원이 자신의 키를 직접 생성하도록 하십시오. 팀 작업 공간의 경우, 편집자(Editor) 역할 이상의 권한을 가진 구성원은 해당 작업 공간 범위 내에서 키를 생성할 수 있습니다.